# TikTok Ads Library search API

> Search TikTok's public Ads Library (ads shown in Europe) by keyword or by advertiser name: advertiser, headline, videos and images, first and last day shown and the library's bracket of people reached. A transparency record of all ads, not the Creative Center's showcase.

Canonical page: https://okdata.online/apis/tiktok/ads/search/

- **Endpoint**: `GET /v1/tiktok/ads/search`
- **ID**: `tiktok.ads.search`
- **Price**: $0.004 per call · about 12 ads per page
- **Returns**: a page of about 12 ads (`data.items`, Ad objects)
- **Status**: beta
- **Good for**: Ad intelligence, Competitor monitoring

## Price

One call costs $0.004 and returns one page of about 12 ads. Collecting 1,000 ads takes about 84 calls, $0.336 in total. Each page is a separate call; failed calls are not charged.

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | no |  | Keywords. Give query or advertiser. (e.g. `espresso`) |
| `advertiser` | string | no |  | The advertiser's name. Give query or advertiser. (e.g. `FIGS INC`) |
| `cursor` | string | no |  | Opaque cursor from page.next_cursor of the previous call. Each page is a separate call. |
| `view` | string: compact / standard / full | no | `standard` | How much of each object comes back. full adds platform-specific fields under ext. |
| `fields` | string | no |  | Comma-separated fields to keep, to save tokens. |

cursor, view and fields work as described in [Requests](https://okdata.online/docs/requests/).

## Returned fields

Each item is a [Ad](https://okdata.online/docs/objects/ad/).

| Field | Type | Description |
|---|---|---|
| `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. |

## Request examples

### cURL

```bash
curl "https://api.okdata.online/v1/tiktok/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY"
```

### Python

```python
import os
import requests

resp = requests.get(
    "https://api.okdata.online/v1/tiktok/ads/search",
    headers={"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"},
    params={},
    timeout=60,
)
body = resp.json()
if body["code"] != "ok":
    raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")

for row in body["data"]["items"]:
    print(row["advertiser"]["name"], row["first_shown_at"], row["text"][:60])
print("cost: $" + body["meta"]["billing"]["amount"])
```

### TypeScript

```ts
const url = new URL('https://api.okdata.online/v1/tiktok/ads/search');

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.OKDATA_API_KEY}`,
  },
});
const body = await res.json();
if (body.code !== 'ok') throw new Error(`${body.code}: ${body.message}`);

for (const row of body.data.items) {
  console.log(row.advertiser.name, row.first_shown_at, row.text.slice(0, 60));
}
console.log('cost: $' + body.meta.billing.amount);
```

### MCP

```json
{
  "name": "call",
  "arguments": {
    "endpoint": "tiktok.ads.search",
    "params": {}
  }
}
```

Or ask an agent that has the MCP server connected:

> Use TikTok Ads Library search and sum up what these ads promise, which offers they push and since when.

## Response example

```json
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "items": [
      {
        "id": "1879699044062290",
        "url": "https://library.tiktok.com/ads/detail/?ad_id=1879699044062290",
        "advertiser": {
          "id": null,
          "name": "Trail Kit Outdoors Ltd",
          "url": null
        },
        "title": "Espresso is Back",
        "text": "Espresso is Back",
        "format": "video",
        "images": null,
        "videos": [
          "https://library.tiktok.com/api/v1/cdn/video/1879699044062290.mp4"
        ],
        "landing_url": null,
        "cta": null,
        "platforms": [
          "tiktok"
        ],
        "active": null,
        "first_shown_at": "2026-11-10T08:00:00Z",
        "last_shown_at": "2026-11-11T08:00:00Z",
        "reach": "1K-10K"
      }
    ]
  },
  "page": {
    "next_cursor": "eyJvIjoyMH0",
    "has_more": true
  },
  "warnings": [],
  "meta": {
    "capability": "tiktok.ads.search",
    "billing": {
      "amount": "0.004",
      "currency": "USD",
      "balance_after": "9.996"
    },
    "unavailable": {},
    "cached": false,
    "replayed": false,
    "fetched_at": "2026-11-11T08:00:00Z"
  }
}
```

## Errors

Errors share one shape and are never charged, except a timeout, whose charge is unknown until looked up. The full table: https://okdata.online/docs/errors/

## Questions

### How much does the TikTok Ads Library search API cost?

One call costs $0.004 and returns one page of about 12 ads. Collecting 1,000 ads takes about 84 calls, $0.336 in total. Each page is a separate call; failed calls are not charged.

### How do I get the next page?

Pass page.next_cursor from the response back as the cursor parameter. When page.has_more is false there is nothing left. Every page is its own call at $0.004.

### Do I need a TikTok account, cookies or a QR login?

No. You send only your okdata API key. The data is public data from TikTok; nothing is fetched with your own TikTok account.

### Am I charged when a call fails?

No. Every error response says charged: false, except a timeout, which says charged: null until the outcome is known. Resend with the same Idempotency-Key and you are never charged twice.

### What if TikTok does not show a field?

The field is null, and meta.unavailable names it with the reason: platform (the platform never shows it) or capability (we cannot fetch it yet).

## More TikTok endpoints

- [TikTok video search](https://okdata.online/apis/tiktok/videos/search/): $0.002 per call · about 30 videos per page
- [TikTok video detail](https://okdata.online/apis/tiktok/videos/get/): $0.002 per call
- [TikTok video comments](https://okdata.online/apis/tiktok/videos/comments/list/): $0.002 per call · about 50 comments per page
- [TikTok account profile](https://okdata.online/apis/tiktok/users/get/): $0.002 per call
- [TikTok Creative Center top ads](https://okdata.online/apis/tiktok/creative_center/ads/search/): $0.002 per call · about 20 ads per page
- [TikTok Shop product search](https://okdata.online/apis/tiktok/shop/products/search/): $0.004 per call · about 20 products per page
- [TikTok Shop product detail](https://okdata.online/apis/tiktok/shop/products/get/): $0.002 per call
- [TikTok Shop product reviews](https://okdata.online/apis/tiktok/shop/products/reviews/list/): $0.002 per call · about 20 reviews per page

## Answers that use this endpoint

- [How do I see all the ads a competitor is running on Meta, Google and TikTok?](https://okdata.online/answers/competitor-ads-meta-google-tiktok/): Query each public ad library under the name the competitor has there (its Facebook page on Meta, its website domain on Google, its advertiser name in TikTok's library) and merge the results into one table. With okdata a weekly sweep of one competitor costs $0.028, and ten competitors every week for a month cost $1.12.