TikTok Creative Center Top Ads API
TikTok Creative Center Top Ads — one ~20-row leaderboard page, not a library search (flat 2; ~1/ad on the fallback path).
q filters the top-N Creative Center leaderboard; it is not a library search. To find a known advertiser's ads, use /v1/ad-library/tiktok/ad-details by ad id. Pull high-performing auction ads from one signed top_ads/v2/list page (~20 rows) as clean JSON: id, url (per-ad detail page), title, brandName (= advertiser.name when present), advertiser{id,name}, likes + likesIsApproximate, ctr, costTier when present, resolved industry/industryKey, objective, and video{} (urlHd only when a distinct HD rendition exists). limit (default 20, max 20) only trims that page — it cannot grow the pool. Creative Center does not expose ad run dates on the list surface — use /tiktok/ad-details (DSA) for firstShown/lastShown (search omits them). Optional ctrTier/isSparkAd appear only when upstream ships them (never null-padded). Keyword q is case-insensitive whole-word match=any|all on title/brandName/industry/objective (hair ≠ wheelchair). There is no tags field. advertiser.name is often null in the default US market, so brand search cannot match there. Each literal hit includes matchedFrom (field names that matched) and the envelope reports candidatesScanned/filteredOut/literalMatches (null when q is omitted)/matchBasis/truncatedReason. When no title/brand whole-word hits, ads[] is still TikTok's keyword-ranked page (matchBasis=ranked, literalMatches=0) — the same list Creative Center shows — not an empty miss. Empty results and upstream timeouts are never charged. A real browser is required — Creative Center HTML is an empty shell and the list API needs page-signed requests. We intercept the signed list XHR and exit when that JSON arrives (typically 30-60 seconds; not networkidle). Flat 2 credits on the native path; the fallback path bills ~1 credit per returned ad (min 2; ~20 at default limit). truncatedReason is limit (your cap trimmed the page) or leaderboard-page (the page was short and Creative Center still had more); null when truncated is false. Pass cache=true for a 24h hit (0 credits).
Request
- Base URL: https://api.captapi.com
- URL: https://api.captapi.com/v1/ad-library/tiktok/top-ads
- Auth: one of:
- HTTP bearer
- API key in header X-API-Key
Query parameters
Optional keyword that ranks the one ~20-row leaderboard page — not a library search. Case-insensitive whole-word hits on title/brandName/industry/objective (hair ≠ wheelchair) come first; the rest of TikTok's keyword-ranked page follows as fill (matchedFrom [] on those ads, rankedFill in the envelope). There is no tags field. advertiser.name is often null in the default US market. Envelope candidatesScanned is the pre-filter pool size. For a known advertiser, use /tiktok/ad-details by ad id.
Keyword token mode: "any" (default, OR) or "all" (AND). Zero whole-word hits still return TikTok's keyword-ranked page as matchBasis=ranked (literalMatches=0).
Two-letter ISO country code. Default US. Non-ISO codes are a definitive 400 INVALID_COUNTRY (Creative Center used to quietly return an empty leaderboard for them).
Lookback window in days: 7, 30, or 180. Default 30.
Sort: for_you, likes, ctr, impressions, or cost. Default for_you.
Optional industry key or label from Creative Center.
Optional campaign objective (e.g. Traffic, Conversion, Reach).
Optional format filter: spark or non_spark. Served only by the extended fetcher — while it is disabled, adFormat returns 503 filter_unavailable (retryable false, not billed). Omit adFormat for the native leaderboard.
Max items to return (default 20, max 20). One Creative Center leaderboard page is ~20 rows; limit only trims that pool — it cannot scan more candidates. Flat 2 credits on the native path; the fallback path ~1 credit per returned ad (min 2).
Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.
Response
Success. The data object for this endpoint.
Changes
No recorded changes to this operation across all 3 revisions of this API.