TikTok Ad Library

GET /v1/ad-library/tiktok/top-ads

TikTok Creative Center Top Ads API

TikTok Creative Center Top Ads — browser-intercepted list XHR, CTR/likes, video (flat 2 / ~1 Apify).

~20 credits (1/result) per request

Try in Playground Get your API key — free Read the docs

TL;DR

TikTok Creative Center Top Ads — browser-intercepted list XHR, CTR/likes, video (flat 2 / ~1 Apify). The TikTok Creative Center Top Ads API (TikTok Ad Library) is a single authenticated GET request to /v1/ad-library/tiktok/top-ads that responds with clean JSON and costs ~20 credits (1/result). Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.

What is the TikTok Creative Center Top Ads API?

Pull high-performing auction ads from TikTok Creative Center Top Ads as clean JSON: id, url (per-ad detail page), title, brandName (= advertiser.name), advertiser{id,name}, likes + likesIsApproximate, ctr, costTier when present, resolved industry/industryKey, objective, and video{} (urlHd only when a distinct HD rendition exists). 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/brand/tags/industry (hair ≠ wheelchair); each hit includes matchedFrom (field names that matched) and the envelope reports candidatesScanned/filteredOut/literalMatches/matchBasis — zero literal hits return empty ads[], never the unfiltered leaderboard. 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 top_ads/v2/list XHR and exit when that JSON arrives (typically 30-60 seconds; not networkidle). Flat 2 credits on the browser path; Apify fallback ~1 credit per returned ad (min 2; ~20 at default limit). truncated:true only when a non-empty page is shorter than limit while Creative Center still has pages (empty after filter → truncated:false). Pass cache=true for a 24h hit (0 credits).

What you get

advertiser{id,name} for grouping + Spark author fallback
Honest keyword filter — per-ad matchedFrom + candidatesScanned envelope
No always-null date/flag fields (CC list has no run dates)
Signed list XHR early-exit (30–60s typical); empty/timeout free

Platform limits

Honest ceilings from the upstream platform surface — not Captapi bugs. Unexpected truncation here is usually the platform, not us.

This endpoint queries TikTok Creative Center live in a browser and typically takes 30-60 seconds. Set your HTTP client timeout to at least 120 seconds. Note that nginx and AWS ALB default to 60s and Heroku caps at 30s.
Creative Center HTML has no ad data — unsigned list API calls return no permission. Anonymous access may be capped; truncated:true means we exited before filling limit while more pages existed.

Try it

Open in Playground

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

Parameters

qoptionalstringOptional 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.matchoptionalstringKeyword token mode: "any" (default, OR) or "all" (AND). Zero literal hits → empty ads[] (never an unfiltered soft list).countryoptionalstringTwo-letter ISO country code. Default US.periodoptionalnumberLookback window in days: 7, 30, or 180. Default 30.orderByoptionalstringSort: for_you, likes, ctr, impressions, or cost. Default for_you.industryoptionalstringOptional industry key or label from Creative Center.objectiveoptionalstringOptional campaign objective (e.g. Traffic, Conversion, Reach).adFormatoptionalstringOptional format filter: spark or non_spark.limitoptionalintegerMax items to return (default 20, max 100). Flat 2 credits on Decodo-native; Apify ~1 credit per returned ad (min 2).cacheoptionalbooleanSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. Envelope includes cached + cachedAt on hits.

API keyoptionalPaste your key to get a ready-to-run snippet. It stays in your browser.Sign in to run live

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

Edit the parameters and the code updates instantly. Switch languages and hit copy.

Example response

{
  "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 is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success, cached, creditsUsed, and a data object with the following fields:

Top-level fields

queryThe search query you sent.
countryCountry for the request context. On popular-creators top-level: ISO feed market you queried (e.g. US) — not each creator's home country (see region).
periodPeriod. Example: 30.
orderByOrder by. Example: "ctr".
totalReturnedNumber of items returned in this response.
datesPresentDates present. Example: 1.
matchEcho of the match query param ("any" or "all").
matchedFromPer-ad only, and only when q is set: string[] of fields that matched (title, brandName, industry, tags, objective). Never the envelope scan count.
filteredOutRows dropped by the local whole-word keyword filter.
literalMatchesPresent only when q is set. Count of rows that passed local whole-word matching.
matchBasisany|all when q was set (literal filter applied); none when q was omitted. Never creative_center — soft leaderboard echoes were removed.

Each item in ads contains:

platformPlatform identifier for this response (matches the endpoint's platform).
idStable platform ID for the item.
urlCanonical URL of the item.
titleTitle of the item.
brandNameSame as advertiser.name when present. Spark Ads with "Not Mention" fall back to the organic creator. Omitted only when no name exists.
advertiserGrouping axis {id,name}. id may be brand_id or Spark author uid; null when Creative Center withholds it. name mirrors brandName (Spark falls back to creator nickname).
firstSeenFirst seen. Example: "2026-01-10T00:00:00.000Z".
lastSeenLast seen.
likesLike count (number).
likesIsApproximatetrue when likes looks like a rounded Creative Center bucket (e.g. multiples of 1k/100k); false when the integer looks exact.
ctrClick-through rate signal from Creative Center (typically 0–1).
ctrTierPresent only when Creative Center ships a CTR bucket. Omitted (not null) when withheld.
costTierRelative spend signal from Creative Center (0–5 style tier).
isSparkAdPresent only when upstream sets Spark/non-Spark. Omitted when withheld. adFormat is omitted when it would only repeat Spark/Non-Spark.
industryIndustry. Example: "Charity & Public Welfare".
industryKeyCreative Center industry key / label id.
objectiveObjective. Example: "Reach".
videoObject with id, url, urlHd, cover, durationSeconds, width.

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.

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs ~20 credits (1/result) — billed per result, so the exact amount scales with how many items you request. Pass cache=true for a free 24h cache hit; default is always fresh (metrics refresh within ~1 hour).

Using an AI agent? This endpoint is the MCP tool tiktok_ad_library_top_ads via @captapi/mcp. Set it up →

How it works

1. Sign up — get 100 free credits, no card required.
2. Create a key from your dashboard.
3. Send one request to /v1/ad-library/tiktok/top-ads and parse the JSON response.

Use cases

Trend Discovery

Find trending content by keyword or hashtag.

Content Sourcing

Build feeds and playlists programmatically.

Monitoring

Track topics, brands, and competitors.

Research

Sample large sets of content for analysis.

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?+

At the default limit this endpoint costs 20 credits (1 per result). Billing scales with how many results you request. 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.

More TikTok Ad Library APIs

TikTok Ad Library Search API TikTok Ad Details API

Ready to use the TikTok Creative Center Top Ads API?

Get started free