Skip to content
truescrape
Free key

Contents

Site

TikTok Ad Library Ad API

Open in ChatGPTOpen in ClaudeOpen in Gemini

One TikTok ad by id or URL. Two public surfaces carry ads and an id alone does not say which: Creative Center Top Ads (ads.tiktok.com) is checked first, then the Commercial Content Library (library.tiktok.com). Pass a URL from either and only that source is queried. Both return the same Ad shape; fields a source does not publish are null rather than inferred - Top Ads carries no flight dates or advertiser entity, and the library carries no performance metrics. countries here is the ad's own targeting, unlike a search result's, where it is the market that was searched. An id neither source knows is a 404; an id that only one source could be asked about is not, because a source that did not answer has not said no. Reach bands stay in raw, not in the impressions fields, because reach is not impressions. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/tiktok/ad-library/ad
ParameterTypeRequiredDescription
ad_idstringyesNumeric ad id, a library.tiktok.com /ads/detail?ad_id= URL, or an ads.tiktok.com Top Ads URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/ad-library/ad?ad_id=1873863495056546&cache_max_age=7d" \
  -H "x-api-key: $KEY"
JavaScript
const query = new URLSearchParams({
  ad_id: '1873863495056546',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/ad-library/ad?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/ad-library/ad",
    params={
        "ad_id": "1873863495056546",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on , with raw removed and lists cut to two items. A live call returns current data.

response
{
  "success": true,
  "data": {
    "platform": "tiktok",
    "id": "1873863495056546",
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "url": "https://library.tiktok.com/ads/detail?ad_id=1873863495056546",
    "headline": "Une rentrée signée Nike",
    "body": null,
    "ctaText": "Shop now",
    "linkUrl": "https://www.nike.com/fr/w/back-to-school-840ik?utm_source=tiktok&utm_id=__CAMPAIGN_ID__&utm_campaign=__CAMPAIGN_NAME__&utm_medium=paid",
    "creativeType": "video",
    "imageUrls": [
      "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o45YWEpAPPkA1b7rAaQtUzIUwB1TiinKIZB1r~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=15aafad7&x-expires=1792566000&x-signature=nS%2BXW0dUBRdARAoIZabgTvZ2%2FdA%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1"
    ],
    "videoUrls": [
      "https://library.tiktok.com/api/v1/cdn/1792547995/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS9jYTlhMTMwMTY1NTQ0NzVmYjI0ZjU0MmMyYzhjYTBmYi82YWQ4NzEwMS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTAwNTFjMDAxLXNnL29vdzdQaTFVYXpacmtZSWpBVUFiaVhGRXFOQmlQbjExWFRBV0kv/9a30ced3-51df-45dc-9fd2-9a420e34979b?a=475769&bt=1148&btag=e000b0000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThDpAFGXq8Zmo&l=202610210959558D331A04AA78BB3D295B&mime_type=video_mp4&rc=OGk0PDNkaDw4ZTQ5aWk1PEBpMzR4PHg5cjM3ZDMzODYzNEBeYzMwMDAvNmExLl8uYy01YSMyNmwxMmRzby9hLS1kMDFzcw%3D%3D&signature=DeMz5%2Fm7VlntHlN0LjvfPNY3wKcjM4TtKA%2FGnFLwWKY%3D&vvpl=1"
    ],
    "platforms": [
      "tiktok"
    ],
    "countries": [
      "FR"
    ],
    "languages": [],
    "startedAt": "2026-08-20T00:00:00.000Z",
    "endedAt": "2026-09-13T00:00:00.000Z",
    "isActive": null,
    "impressionsLower": null,
    "impressionsUpper": null,
    "spendLower": null,
    "spendUpper": null,
    "currency": null,
    "fetchedAt": "2026-10-21T01:59:56.154Z"
  },
  "meta": {
    "platform": "tiktok",
    "endpoint": "tiktok.adLibraryAd",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 6523,
    "requestId": "req_gu2gja8pubgjtm297gwy"
  }
}

Returns

Returns one Ad.

Cost and behaviour

Credits1 per live request, 0 on a cache hit
Cacheableyes: cache_max_age accepts a cached copy
Batchableyes: usable as a target in POST /v1/jobs/batch
Subscribableyes: as often as every 3600 seconds, firing a webhook only on a change

Other TikTok endpoints

All TikTok endpointsThe unified schema