Docs · TikTok Ad Library ad

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.

1 credit per callFresh within 3 hoursMCP tool: tiktok_ad_library_ad

GEThttps://api.lurkapi.com/v1/tiktok/ad-library/ad

Example response View as markdown

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.

Parameter	Description
`ad_id` stringrequired	The ad's `id` from TikTok Ad Library search, e.g. `1876319908813409`, or its library.tiktok.com/ads/detail/?ad_id=… URL. Example `1876319908813409`

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

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 · reads your key from LURKAPI_KEY

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

Show the example response (2 KB)

{
  "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.

Show all 46 fields

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	stringnullable	The advertiser as registered with TikTok; null for the few ads published without one.
title	stringnullable	The ad's caption text; null if it has none.
category	stringnullable	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	stringnullable	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	stringnullable	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	stringnullable	Where the ad sends people: the landing page, or the app store page for app ads; null if none.
call_to_action	stringnullable	The button text, e.g. `Shop now`; null if none.
objective	stringnullable	The advertiser's campaign objective, e.g. `Traffic` or `Sales`; null if not given.
advertiser	object	Who ran the ad.
advertiser.name	stringnullable	The advertiser as registered with TikTok.
advertiser.adv_biz_ids	stringnullable	TikTok's business id for the advertiser, e.g. `6876453864464188162`.
advertiser.registry_location	stringnullable	Country the advertiser is registered in, e.g. `Germany`.
advertiser.sponsor	stringnullable	Who paid for the ad ("Ad paid for by"), often an agency or the advertiser itself; null if not given.
advertiser.tiktok_user	objectnullable	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	stringnullable	Display name.
advertiser.tiktok_user.followers	stringnullable	Followers as TikTok rounds them in the library, e.g. `319.1K`.
advertiser.tiktok_user.avatar_url	stringnullable	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	stringnullable	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). All error codes.

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, this endpoint is the tiktok_ad_library_ad tool. Ask in plain English, for example:

Ask Claude

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

{
  "ad_id": "1876319908813409"
}

Tool results skip nulls and empty lists to save tokens.