# 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…

Canonical page: https://okdata.online/roles/ads-search/

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.

## on each platform

| Platform | Endpoint | Path | A page | Price |
|---|---|---|---|---|
| Meta Ad Library | [Meta Ad Library search](https://okdata.online/apis/meta/ads/search/) | `GET /v1/meta/ads/search` | 30 | $0.004 per call · about 30 ads per page |
| TikTok | [TikTok Ads Library search](https://okdata.online/apis/tiktok/ads/search/) | `GET /v1/tiktok/ads/search` | 12 | $0.004 per call · about 12 ads per page |
| TikTok | [TikTok Creative Center top ads](https://okdata.online/apis/tiktok/creative_center/ads/search/) | `GET /v1/tiktok/creative_center/ads/search` | 20 | $0.002 per call · about 20 ads per page |

## The object it returns: [Ad](https://okdata.online/docs/objects/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.

```bash
# 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.

## Other data types

- [Comments API](https://okdata.online/roles/posts-comments-list/)
- [Trending topics API](https://okdata.online/roles/trends-list/)
- [Comment replies API](https://okdata.online/roles/comments-replies-list/)
- [Hashtag posts API](https://okdata.online/roles/topics-posts-list/)
- [Profile API](https://okdata.online/roles/accounts-get/)
- [Account posts API](https://okdata.online/roles/accounts-posts-list/)
- [Post detail API](https://okdata.online/roles/posts-get/)
- [Post search API](https://okdata.online/roles/posts-search/)
- [Trending posts API](https://okdata.online/roles/posts-trending/)
- [Account search API](https://okdata.online/roles/accounts-search/)
- [Post metrics API](https://okdata.online/roles/posts-metrics/)
- [Community posts API](https://okdata.online/roles/communities-posts-list/)
- [Ad detail API](https://okdata.online/roles/ads-get/)
- [Advertiser ads API](https://okdata.online/roles/advertisers-ads-list/)
- [Transcript API](https://okdata.online/roles/transcripts-get/)
- [Followers list API](https://okdata.online/roles/accounts-followers-list/)
- [Product detail API](https://okdata.online/roles/products-get/)
- [Product reviews API](https://okdata.online/roles/products-reviews-list/)
- [Product search API](https://okdata.online/roles/products-search/)
- [Creator search API](https://okdata.online/roles/creators-search/)
- [Creator profile API](https://okdata.online/roles/creators-get/)
- [Creator audience API](https://okdata.online/roles/creators-audience-get/)