How to run a TikTok Ad Library top ads
GET request to /v1/ad-library/tiktok/top-ads with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. TikTok Creative Center Top Ads — browser-intercepted list XHR, CTR/likes, video (flat 2 / ~1 Apify).How to run a TikTok Ad Library top ads (step by step)
- 1
Get a free API key
Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.
- 2
Call the TikTok Creative Center Top Ads API
Send an authenticated GET request to /v1/ad-library/tiktok/top-ads with your input. No OAuth, no scraping setup.
- 3
Read the JSON response
Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.
Code example
curl "https://api.captapi.com/v1/ad-library/tiktok/top-ads?q=skincare" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."What the response looks like
{
"success": true,
"data": {
"query": null,
"country": "US",
"period": 30,
"orderBy": "ctr",
"totalReturned": 2,
"datesPresent": 1,
"match": "any",
"matchedFrom": 2,
"filteredOut": 0,
"literalMatches": 2,
"matchBasis": "none",
"ads": [
{
"platform": "tiktok_creative_center",
"id": "7662489073849090066",
"url": "https://ads.tiktok.com/business/creativecenter/topads/7662489073849090066/pc/en",
"title": "Nuuly loves a woman in a suit ! #ad #nuulypartner #nuuly #frthoidolovenuuly",
"brandName": "nuuly",
"advertiser": {
"id": "brand_nuuly",
"name": "nuuly"
},
"firstSeen": "2026-01-10T00:00:00.000Z",
"lastSeen": null,
"likes": 620,
"likesIsApproximate": false,
"ctr": 0.17,
"ctrTier": "below_50%",
"costTier": 1,
"isSparkAd": false,
"industry": "Charity & Public Welfare",
"industryKey": "label_23105000000",
"objective": "Reach",
"video": {
"id": "v10033g50000example",
"url": "https://v16m-default.tiktokcdn.com/example.mp4",
"urlHd": "https://v16m-default.tiktokcdn.com/example-hd.mp4",
"cover": "https://p16-common-sign.tiktokcdn.com/example~tplv-noop.image",
"durationSeconds": 15,
"width": 720,
"height": 1280
}
},
{
"platform": "tiktok_creative_center",
"id": "7662938725836324871",
"url": "https://ads.tiktok.com/business/creativecenter/topads/7662938725836324871/pc/en",
"title": "How I fix my hair EASILY on the go #hair #hairhack",
"brandName": "Creator X",
"advertiser": {
"id": "uid42",
"name": "Creator X"
},
"firstSeen": null,
"lastSeen": null,
"likes": 5,
"likesIsApproximate": false,
"ctr": 0.62,
"ctrTier": "top_25%",
"costTier": 0,
"isSparkAd": true,
"industry": "Charity & Public Welfare",
"industryKey": "label_23105000000",
"objective": "Product Sales",
"video": {
"id": "v10033g50000example",
"url": "https://v16m-default.tiktokcdn.com/example.mp4",
"cover": "https://p16-common-sign.tiktokcdn.com/example~tplv-noop.image",
"durationSeconds": 15,
"width": 720,
"height": 1280
}
}
]
}
}Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | No | Optional keyword — case-insensitive whole-word match on title/brand/tags/industry (hair ≠ wheelchair). Each returned ad includes matchedFrom (which fields matched). Envelope candidatesScanned is the pre-filter pool size. |
| match | string | No | Keyword token mode: "any" (default, OR) or "all" (AND). Zero literal hits → empty ads[] (never an unfiltered soft list). |
| country | string | No | Two-letter ISO country code. Default US. |
| period | number | No | Lookback window in days: 7, 30, or 180. Default 30. |
| orderBy | string | No | Sort: for_you, likes, ctr, impressions, or cost. Default for_you. |
| industry | string | No | Optional industry key or label from Creative Center. |
| objective | string | No | Optional campaign objective (e.g. Traffic, Conversion, Reach). |
| adFormat | string | No | Optional format filter: spark or non_spark. |
| limit | integer | No | Max items to return (default 20, max 100). Flat 2 credits on Decodo-native; Apify ~1 credit per returned ad (min 2). |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. Envelope includes cached + cachedAt on hits. |
Frequently asked questions
What does the TikTok Creative Center Top Ads API do?
The TikTok Creative Center Top Ads API lets you search and return matching results from a public TikTok Ad Library query using one GET request to /v1/ad-library/tiktok/top-ads. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the TikTok Creative Center Top Ads API cost?
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Hits include cached + cachedAt. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a TikTok Ad Library API key or OAuth?
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.
How is this different from TikTok Ad Library Search?
Top Ads is Creative Center performance inspiration (CTR tiers, likes, industry/objective, Spark Ads, video renditions). Ad Library Search is the EU Commercial Content Library (first/last shown, reach bands). Different TikTok products — pick Top Ads for creative intel, Search for DSA transparency.
How many credits does Top Ads cost?
Flat 2 credits on Decodo-native when ads are returned. Apify fallback bills ~1 credit per returned ad (min 2) — about 20 credits at the default limit of 20. Empty results and upstream timeouts are never charged. cache=true hits are free.
Why is this endpoint so slow — and what timeout should I set?
Creative Center HTML is an empty shell — ads arrive only via a signed list XHR. We open the page in a browser, intercept that response, and exit when the JSON arrives (typically 30–60 seconds — not networkidle). Set your HTTP client timeout to at least 120 seconds. nginx/ALB default to 60s and Heroku caps at 30s — those cut the connection on your side. On timeout we return 503 upstream_timeout (not billed). If totalReturned < limit and truncated is true, Creative Center still had pages we did not fetch.
Why did my keyword return zero ads?
Read candidatesScanned, filteredOut, literalMatches, and matchBasis. match=any (default) keeps rows with any whole-word token; match=all requires every token. Creative Center's keyword ranking is soft and often unrelated — we never echo that unfiltered list. If candidatesScanned>0 and totalReturned=0, the leaderboard had rows and local filter dropped them (empty is free; truncated is false). Try a brand name or a token that appears in title/industry.
What does ctr mean, and where are ad dates?
ctr is TikTok's normalized 0–1 Creative Center score (not a raw click-through percent). ctrTier/isSparkAd appear only when Creative Center ships them. The list surface does not expose ad run dates — firstSeen/lastSeen are not returned. The period param is only the lookback window for the ranking. For DSA firstShown/lastShown use /tiktok/ad-details (search omits them).
How do I group ads by advertiser?
Use advertiser.id when present, else advertiser.name (same value as brandName). Spark Ads that ship "Not Mention" fall back to the organic creator nickname and author id. Creative Center often omits a stable business id — null advertiser.id is expected on some rows.
Why did Top Ads return 502 with industry set?
The Apify fallback only accepts its fixed industry enum (All Industries, Gaming, E-commerce & Shopping, Beauty & Personal Care, …). We now map TikTok keys/aliases (label_25000000000, Games→Gaming) before the actor call; unsupported values return HTTP 400 with the allowed list — not upstream_actor_error 502. Omit industry or use Gaming / All Industries to unblock.
Is the TikTok Creative Center Top Ads API suitable for production use?
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Hits include cached + cachedAt. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
Ready to run a TikTok Ad Library top ads?
Start free with 100 credits — no credit card required.
Get your free API key