# TikTok Ad Library ad

> One ad from TikTok's EU Ad Library: creative, landing page, advertiser, who paid, targeting and reach by country, age and gender.

- **Request:** `GET https://api.lurkapi.com/v1/tiktok/ad-library/ad`
- **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard))
- **Cost:** 1 credit per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)).
- **MCP tool:** `tiktok_ad_library_ad` on `https://api.lurkapi.com/mcp`
- **Freshness:** responses are cached for up to 3 hours
- **Try it live:** https://lurkapi.com/docs/tiktok/ad-library-ad#try (no signup)
- **Platform:** [TikTok](https://lurkapi.com/docs/tiktok.md) (tiktok.com)
- **Web page:** https://lurkapi.com/docs/tiktok/ad-library-ad

## When to use this

Use it to see how an ad was targeted and whom it reached: the countries, ages, genders and interests the advertiser chose, TikTok's estimate of how many users matched, and unique reach per country (split by age and gender for ads shown since June 2026). You also get the landing page, call to action, objective, who paid for the ad and the advertiser's TikTok account.

Get `ad_id` from TikTok Ad Library search, or paste the ad's library.tiktok.com URL. Like the search, it only covers ads shown in the EU/EEA, Switzerland, the UK and Turkey.

Unknown ids return 404 `not_found`.

## Parameters

All parameters go in the query string.

| Name | Type | Required | Default | Allowed values | Description | Example |
| --- | --- | --- | --- | --- | --- | --- |
| `ad_id` | string | yes |  |  | The ad's `id` from TikTok Ad Library search, e.g. `1876319908813409`, or its library.tiktok.com/ads/detail/?ad_id=… URL. | `1876319908813409` |

## Example request

Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard).

curl:

```bash
curl "https://api.lurkapi.com/v1/tiktok/ad-library/ad?ad_id=1876319908813409" \
  -H "x-api-key: YOUR_API_KEY"
```

JavaScript:

```js
const params = new URLSearchParams({
  ad_id: "1876319908813409",
});
const res = await fetch(`https://api.lurkapi.com/v1/tiktok/ad-library/ad?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.videos);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/tiktok/ad-library/ad",
    params={
        "ad_id": "1876319908813409",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["videos"])
```

## Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in `…`.

200 OK (application/json):

```json
{
  "success": true,
  "credits_remaining": 999986,
  "credits_charged": 1,
  "id": "1876319908813409",
  "url": "https://library.tiktok.com/ads/detail/?ad_id=1876319908813409",
  "advertiser_name": "NIKE Retail B.V.",
  "title": null,
  "category": "Apparel & Accessories",
  "first_shown": 1789344000,
  "last_shown": 1790640000,
  "estimated_audience": "500K-600K",
  "videos": [
    {
      "url": "https://library.tiktok.com/api/v1/cdn/1790776218/video/aHR0cHM6Ly92MTZtL…",
      "cover": "https://p16-common-sign.tiktokcdn.com/tos-useast2a-p-0037-euttp/oAgCkf5X…"
    }
  ],
  "image_urls": [],
  "external_url": "https://www.nike.com/fr/w/air-rift-chaussures-56wtbzy7ok?cp=72924050721_brs_CR9S9EUTR0WV",
  "call_to_action": "Shop now",
  "objective": "Traffic",
  "advertiser": {
    "name": "NIKE Retail B.V.",
    "adv_biz_ids": "6876453864464188162",
    "registry_location": "Netherlands",
    "sponsor": "INITIATIVE MEDIA B.V.",
    "tiktok_user": null
  },
  "targeting": {
    "countries": [
      "FR"
    ],
    "age": [
      "18-24",
      "25-34"
    ],
    "gender": [
      "female"
    ],
    "audience_size": "3.9M-4.8M",
    "interests": [
      "Apparel & Accessories",
      "Sports"
    ],
    "video_interactions": [
      "Beauty & Style"
    ],
    "creator_interactions": [
      "Fashion & Beauty"
    ],
    "languages": [],
    "operating_systems": []
  },
  "reach_by_country": [
    {
      "country": "FR",
      "users": "540K",
      "by_age_gender": [
        {
          "age": "18-24",
          "gender": "female",
          "users": "302K"
        },
        {
          "age": "25-34",
          "gender": "female",
          "users": "254K"
        }
      ]
    }
  ]
}
```

## Response fields

Every field of a successful response. `[]` marks a list: `a[].b` is the `b` of each item in `a`. **nullable** fields can be `null`; **optional** fields can be missing.

| Field | Type | Description |
| --- | --- | --- |
| `success` | `true` | Always true here; errors have `success: false`. |
| `credits_remaining` | `number` | Your balance after this call. On anonymous playground calls: free tries left today. |
| `credits_charged` | `number` | Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1). |
| `id` | `string` | Ad id. Pass it as `ad_id` to TikTok Ad Library ad for targeting and reach. |
| `url` | `string` | The ad on library.tiktok.com. |
| `advertiser_name` | `string`, nullable | The advertiser as registered with TikTok; null for the few ads published without one. |
| `title` | `string`, nullable | The ad's caption text; null if it has none. |
| `category` | `string`, nullable | TikTok's category for the ad, e.g. `Apparel & Accessories` or `Apps`; null if none. |
| `first_shown` | `number` | First day the ad was shown in the library's countries, Unix seconds (midnight UTC). |
| `last_shown` | `number` | Latest day it was shown, Unix seconds (midnight UTC). Yesterday or today for ads still running. |
| `estimated_audience` | `string`, nullable | TikTok's estimate of unique users who saw the ad at least once, as a range such as `10K-100K`; null if not given. |
| `videos` | `object[]` | The ad's videos, usually one. Empty for image ads. |
| `videos[].url` | `string` | MP4 URL. It redirects to TikTok's CDN and expires about 6 hours after we fetched the ad. |
| `videos[].cover` | `string`, nullable | Cover image URL (expires about 6 hours after we fetched the ad); null if none. |
| `image_urls` | `string[]` | The ad's images, in order. Empty for most video ads. |
| `external_url` | `string`, nullable | Where the ad sends people: the landing page, or the app store page for app ads; null if none. |
| `call_to_action` | `string`, nullable | The button text, e.g. `Shop now`; null if none. |
| `objective` | `string`, nullable | The advertiser's campaign objective, e.g. `Traffic` or `Sales`; null if not given. |
| `advertiser` | `object` | Who ran the ad. |
| `advertiser.name` | `string`, nullable | The advertiser as registered with TikTok. |
| `advertiser.adv_biz_ids` | `string`, nullable | TikTok's business id for the advertiser, e.g. `6876453864464188162`. |
| `advertiser.registry_location` | `string`, nullable | Country the advertiser is registered in, e.g. `Germany`. |
| `advertiser.sponsor` | `string`, nullable | Who paid for the ad ("Ad paid for by"), often an agency or the advertiser itself; null if not given. |
| `advertiser.tiktok_user` | `object`, nullable | The advertiser's TikTok account; null when the ad didn't run from one. |
| `advertiser.tiktok_user.username` | `string` | TikTok username (handle), without @. Pass it to the profile endpoint. |
| `advertiser.tiktok_user.display_name` | `string`, nullable | Display name. |
| `advertiser.tiktok_user.followers` | `string`, nullable | Followers as TikTok rounds them in the library, e.g. `319.1K`. |
| `advertiser.tiktok_user.avatar_url` | `string`, nullable | Avatar URL (expires after a few days). |
| `advertiser.tiktok_user.url` | `string` | The account on tiktok.com. |
| `targeting` | `object` | The main ways the advertiser chose to reach people. TikTok may also have shown the ad for other reasons. |
| `targeting.countries` | `string[]` | Countries targeted, as 2-letter codes. |
| `targeting.age` | `string[]` | Age ranges targeted, e.g. `18-24`, `25-34` or `55+` (in any of the countries). |
| `targeting.gender` | `string[]` | Genders targeted: `female`, `male` and/or `unknown`. |
| `targeting.audience_size` | `string`, nullable | TikTok's estimate of how many users matched the targeting, e.g. `3.9M-4.8M`. |
| `targeting.interests` | `string[]` | Interest categories targeted, e.g. `Sports`. Empty if none. |
| `targeting.video_interactions` | `string[]` | Categories of videos the audience interacted with. Empty if not used. |
| `targeting.creator_interactions` | `string[]` | Categories of creators the audience followed or watched. Empty if not used. |
| `targeting.languages` | `string[]` | Languages targeted. Empty means any. |
| `targeting.operating_systems` | `string[]` | Operating systems targeted, e.g. `ANDROID`. Empty means any. |
| `reach_by_country` | `object[]` | Unique users reached, per country. |
| `reach_by_country[].country` | `string` | 2-letter country code. |
| `reach_by_country[].users` | `string` | Unique users reached there, e.g. `540K` or a range like `0-1K`. |
| `reach_by_country[].by_age_gender` | `object[]` | Reach split by age and gender. TikTok only publishes it for ads shown since June 2026; empty otherwise. |
| `reach_by_country[].by_age_gender[].age` | `string` | Age range, e.g. `18-24` or `55+`. |
| `reach_by_country[].by_age_gender[].gender` | `string` | `female`, `male` or `unknown`. |
| `reach_by_country[].by_age_gender[].users` | `string` | Unique users reached in this group, e.g. `302K` or `0-1K`. |

## Caching and freshness

Responses are cached for up to 3 hours, so a repeat call within that window can return the same data. It still costs 1 credit.

## Errors

Errors return `{ success: false, error, code, docs }` with the HTTP status below. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors).

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `missing_api_key` | No API key. Send it in the `x-api-key` header. |
| 401 | `invalid_api_key` | The key is unknown or was revoked. |
| 402 | `insufficient_credits` | Not enough credits for this call. Buy a pack or wait for tomorrow's top-up. |
| 404 | `not_found` | The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked. |
| 405 | `method_not_allowed` | Endpoints take GET with query params. |
| 429 | `rate_limited` | Too many calls at once. Wait for the `retry-after` seconds, then retry. |
| 500 | `internal_error` | Something broke on our side. Retry; 5xx errors are free. |
| 502 | `upstream_error` | The platform didn't give a usable answer. Retry; 5xx errors are free. |
| 503 | `upstream_busy` | All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free. |
| 504 | `upstream_timeout` | The platform took over 30 seconds to answer. Retry; timeouts are free. |

## Use it in Claude

Once LurkAPI is [connected to Claude](https://lurkapi.com/docs.md#claude), this endpoint is the `tiktok_ad_library_ad` tool. Ask in plain English, for example:

Ask Claude:

```text
Use LurkAPI's tiktok_ad_library_ad with ad_id "1876319908813409" and summarize what you find.
```

Claude calls `tiktok_ad_library_ad` with arguments like these, and each call costs 1 credit:

Tool arguments:

```json
{
  "ad_id": "1876319908813409"
}
```

Tool results skip nulls and empty lists to save tokens.

---

Previous: [Search TikTok Ad Library](https://lurkapi.com/docs/tiktok/ad-library-search.md) · Next: [Live status](https://lurkapi.com/docs/tiktok/live.md)