Endpoints by data type
Ad detail API
2 endpoints on 2 platforms return ad details as the same Ad object. One ad from a public ad library by its ID or link: the advertiser, copy, images or video, landing page, where it runs, when it was first and last shown, and whether it is still running. A call costs from $0.002 to $0.004, each endpoint at its own price; a failed call is free.
Ad detail · on each platform
| Platform | Endpoint | Path | A page | Price |
|---|---|---|---|---|
| Meta Ad Library | Meta Ad Library ad detail | GET /v1/meta/ads/get | 1 | $0.004 per call |
| TikTok | TikTok Creative Center top ad | GET /v1/tiktok/creative_center/ads/get | 1 | $0.002 per call |
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/get" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=744979408183770'
# TikTok
curl -G "https://api.okdata.online/v1/tiktok/creative_center/ads/get" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=7686210433094729735'What people use it for
- Save the full creative of a competitor ad someone sent you as a link.
- Check whether an ad you saw last month is still running.
Questions
- Where do I get an ad’s ID?
- From an ad search or advertiser ads result, or from the ad’s own link in the library. Either the ID or the link works.
- Can I see spend and results?
- Only what the library publishes. A field the library does not publish comes back null and is named in meta.unavailable; reach is filled only where the library gives a bracket or a count.
- How do I know it is still running?
- Read active and last_shown_at. A running ad has active set to true, where the library says so, and a recent last shown date.