Endpoints by data type
Ad search API
3 endpoints on 2 platforms return ads as the same Ad object. Ads in public ad libraries that match a keyword or an advertiser name, a page at a time: advertiser, copy, images or video, landing page, where they run and since when. A call costs from $0.002 to $0.004, each endpoint at its own price; a failed call is free.
Ad search · on each platform
| Platform | Endpoint | Path | A page | Price |
|---|---|---|---|---|
| Meta Ad Library | Meta Ad Library search | GET /v1/meta/ads/search | 30 | $0.004 per call · about 30 ads per page |
| TikTok | TikTok Ads Library search | GET /v1/tiktok/ads/search | 12 | $0.004 per call · about 12 ads per page |
| TikTok | TikTok Creative Center top ads | GET /v1/tiktok/creative_center/ads/search | 20 | $0.002 per call · about 20 ads per page |
from $0.002 to $0.004 a call, each endpoint at its own price. A call that fails costs nothing.
The object it returns: Ad
Every endpoint above returns these fields with the same names and types. A field a platform does not show comes back null and is named in meta.unavailable.
| Field | Type | Meaning |
|---|---|---|
id | string | Ad ID in the library. |
url | string | Link to the ad in the library. |
advertiser | AdvertiserRef | Who runs the ad. |
title | string | null | Headline, where the ad has one. |
text | string | Ad copy as plain text; empty when the ad has none. |
format | string | null | Creative format; dynamic means the platform assembles it per viewer (catalog ads). |
images | string[] | null | Image URLs of the creative. |
videos | string[] | null | Video URLs of the creative. |
landing_url | string | null | Where the ad leads. |
cta | string | null | Call-to-action button text. |
platforms | string[] | null | Where it is delivered, e.g. facebook, instagram. |
active | boolean | null | Whether the ad is still running. |
first_shown_at | string | null | First time or day shown, ISO 8601 in UTC. |
last_shown_at | string | null | Last time or day shown, ISO 8601 in UTC. |
reach | string | null | People reached, as the library publishes it: a bracket such as 1K-10K, or a count (the EU reach of a Meta ad); null where none is published. |
ext | object | Platform-specific extras. Only returned with view=full. |
The same call on two platforms
Same parameters, same paging, same response shape. Only the path changes.
# Meta Ad Library
curl -G "https://api.okdata.online/v1/meta/ads/search" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'query=portable espresso'
# TikTok
curl "https://api.okdata.online/v1/tiktok/ads/search" \
-H "Authorization: Bearer $OKDATA_API_KEY"What people use it for
- See which brands advertise on a keyword such as a product category.
- Build a swipe file of the ads in your niche.
- Find out how long competitors keep the same creative running.
Questions
- Do these cover every ad?
- The Meta Ad Library and TikTok’s Ads Library are transparency records, each within its own rules on regions and ad types. TikTok’s Creative Center is a showcase of ads that did well, not every ad, and has no run dates.
- Can I filter by country?
- Meta search and Creative Center search take a country. TikTok’s Ads Library covers ads shown in Europe. The parameters are on each endpoint page.
- Can I download the creative?
- images and videos hold the media URLs wherever the library exposes them. Save the files on your side if you need them later.