TikTok Creative Center API & Scraper
The TikTok Creative Center API returns TikTok ad-spy and creative intelligence as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary top_ads endpoint returns top-performing ads with title, brand, CTR, likes, cost, industry, objective and the video itself, and you can pull an ad_detail, search_ads, ad_filters, query_suggestions, trend_reports and locations. It is built for ad-intelligence, competitor-research and creative-strategy tools that need TikTok ad-library data without a login. One ReefAPI key, one shared credit pool, the standard envelope.
What the Top Ads metrics actually measure, and which filter vocabularies are real
The metric names on these ads look like advertising numbers you can spend against, and two of them are not. This table says what each one is on the wire. Everything was measured on 2026-08-27 with top_ads and ad_detail for region US, period 30, plus the ad_filters and locations taxonomies.
| Field or parameter | Measured | What it means |
|---|---|---|
| ctr | 0.01 through 0.88 across 20 ads | A percentage, not a ratio. 0.88 means 0.88 percent, measured over the period window |
| cost | Only the values 0, 1 and 2 appeared across 20 ads | A coarse spend bucket TikTok publishes in place of a currency amount. There is no money figure anywhere in this engine |
| like, comment, share | 347,148 likes on the top row; 5 comments and 17 shares on one ad_detail | Absolute counts accumulated over the period window |
| period | 7, 30 and 180 only | Anything else falls back to 30. ad_filters.period labels them seven_day, thirty_day and half_year |
| order_by | for_you, ctr and like all returned data; cost was rejected | cost fails with UPSTREAM_HTTP: "Field validation for 'OrderBy' failed on the 'oneof' tag" |
| industry_key | "label_20112000000" | Join it to ad_filters.industry, whose 258 entries each carry id, a human value such as Games or Outdoor Equipment, the same label string, and parent_id |
| objective_key | "campaign_objective_reach" | One of 7. ad_detail also returns objectives[] pairing each label with a numeric value, e.g. product_sales 15 and reach 5 |
| region | locations returned 73 markets, ad_filters.country returned 28 | The two lists disagree. Treat locations as the wider one, and expect an unsupported code to fall back to US |
| pagination.total_count | 178 for region US with period 30 | The size of the ranked index behind those filters, not a page count. page above 1 returns nothing |
| brand_name | null on 7 of 10 rows | Often absent, and ad_title can be an empty string too. Do not key on either |
Measured on 2026-08-27, order_by "ctr" returned ads in ascending CTR order: 0.01, 0.01, 0.02, 0.02, 0.02, 0.04, 0.05, 0.06, 0.06, 0.07 across ten rows. That surfaces the weakest performers first, so sort client-side if you want the top of the distribution. ad_detail adds comment, share, country_code[], landing_page, keyword_list, objectives[], highlight_text, source with source_key, and voice_over, but on the ad measured landing_page came back as an empty string and keyword_list as null.
Real request and response JSON
Captured from the indexed primary action, top_ads, on .
{
"method": "POST",
"url": "https://api.reefapi.com/tiktok-creative-center/v1/top_ads",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"region": "US",
"period": "30"
}
}{
"ok": true,
"meta": {
"api": "tiktok-creative-center",
"endpoint": "top_ads",
"mode": "live",
"latency_ms": 1755.9,
"record_count": 20,
"bytes": 46126,
"cache_hit": false,
"stop_reason": "limit_reached",
"region": "US",
"period_days": 30
},
"data": {
"ads": [
{
"id": "[redacted-phone]",
"ad_title": "Natural Cycles is the only FDA-cleared and CE-marked birth control app.
From NC° Birth Control to NC° Plan Pregnancy to NC° Perimenopause, Natural Cycles is there to support your long-term fertility journey.
Natural Cycles is 98% effective with perfect use and 93% effective with typical use.
Are you ready to take control of your fertility? Sign up for Natural Cycles today and get a free NC° Band with your annual subscription. Offer available for new users only.",
"brand_name": "natural cycles",
"ctr": 0.36,
"like": 7,
"cost": 1,
"industry_key": "label_[redacted-phone]",
"objective_key": "campaign_objective_conversion",
"is_search": true,
"favorite": false,
"video": {
"vid": "v12044gd0000d8bl3svog65t7cnhjkrg",
"duration": 31.787,
"cover_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068c799-us/oQQE4pzAQd6ES7FBpueDfDuRHzAFJT1gUzXqQl~tplv-noop.image?dr=18692&refresh_token=02c33f5b&x-expires=[redacted-phone]&x-signature=fHNlNyVmKnVtSOauX0LPHxHl%2BkY%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v12044gd0000d8bl3svog65t7cnhjkrg",
"width": 720,
"height": 1280,
"video_urls": {
"540p": "[trimmed-depth]",
"720p": "[trimmed-depth]"
}
}
},
{
"id": "[redacted-phone]",
"ad_title": "Up to 50% OFF! Clip Studio Paint is on sale now until June 23rd, 8:00 AM (UTC)",
"brand_name": null,
"ctr": 0.18,
"like": 148,
"cost": 1,
"industry_key": "label_[redacted-phone]",
"objective_key": "campaign_objective_traffic",
"is_search": true,
"favorite": false,
"video": {
"vid": "v10033g50000d8ofnsfog65t106u4org",
"duration": 97.6,
"cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/osxQe9JfQQoZAWhKjhEM8MctfjAXDfeAccXRgG~tplv-noop.image?dr=18692&refresh_token=c28f9e0e&x-expires=[redacted-phone]&x-signature=KQgye6afrgts3%2B%2FgAXAddrpw%2BRg%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v10033g50000d8ofnsfog65t106u4org",
"width": 720,
"height": 1280,
"video_urls": {
"360p": "[trimmed-depth]",
"480p": "[trimmed-depth]",
"540p": "[trimmed-depth]",
"720p": "[trimmed-depth]",
"1080p": "[trimmed-depth]"
}
}
},
{
"id": "[redacted-phone]",
"ad_title": "Bold, all-natural Borjomi sparkling water has over 60+ natural gut-healthy minerals in every sip. ",
"brand_name": null,
"ctr": 0.34,
"like": 299,
"cost": 2,
"industry_key": "label_[redacted-phone]",
"objective_key": "campaign_objective_traffic",
"is_search": true,
"favorite": false,
"video": {
"vid": "v10033g50000d8hgatvog65iv8gr5tvg",
"duration": 15.019,
"cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o85rQgIGH6eDLLeECUgGG38gueLlIbARbvCAWA~tplv-noop.image?dr=18692&refresh_token=347dcad9&x-expires=[redacted-phone]&x-signature=hu7FMPufQzYJq%2Fw1WWPacyLktqQ%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v10033g50000d8hgatvog65iv8gr5tvg",
"width": 720,
"height": 1280,
"video_urls": {
"360p": "[trimmed-depth]",
"480p": "[trimmed-depth]",
"540p": "[trimmed-depth]",
"720p": "[trimmed-depth]",
"1080p": "[trimmed-depth]"
}
}
}
],
"pagination": {
"page": 1,
"size": 20,
"total_count": 309,
"has_more": true
},
"region": "US",
"period_days": 30
}
}What the TikTok Creative Center API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| top_ads | Top-performing TikTok ads for a market, filterable by region, period, industry, objective and ad language, ranked by recommendation / CTR / likes / spend. The core ad-spy feed — the same Top Ads intelligence PiPiADS / Minea / AdSpy sell as SaaS — with each ad's metrics and full video renditions. | Social-listening tools call top_ads to get top-performing TikTok ads for a market, filterable by region, period, industry, objective and…. | region, period, order_by, industry, objective, ... |
| ad_detail | Full creative record for one ad: title, brand, CTR, spend, likes, comments, shares, landing page, matched keywords, campaign objectives, highlight text, creative source, voice-over flag and the full set of video renditions (360p-1080p). | Creator and influencer platforms call ad_detail to get full creative record for one ad. | ad_id |
| search_ads | Keyword search across TikTok's Top-Ads index (region/period scoped), returning the same ad shape as top_ads. NOTE: TikTok's keyword index is sparse — only terms that match indexed ad metadata return matches, and many generic queries come back empty (honest empty, ok=true). For broad discovery prefer `top_ads` with industry / objective filters. | Brand-monitoring teams call search_ads to get keyword search across TikTok's Top-Ads index (region/period scoped), returning the same ad sh…. | keyword, region, period, limit, page |
| ad_filters | The live filter taxonomy used by top_ads: full country (81), industry (258), objective (7), ad_language (16), pattern_label and period value lists. | Audience analysts call ad_filters to get the live filter taxonomy used by top_ads. | none |
| query_suggestions | Suggested Top-Ads search terms surfaced by TikTok's Creative Center search box. Honestly returns an empty list when TikTok is serving no suggestions for the locale. | Social-listening tools call query_suggestions to get suggested Top-Ads search terms surfaced by TikTok's Creative Center search box. | limit |
| trend_reports | Creative-Center trend reports & creative-guidance articles (official TikTok marketing insight content). | Creator and influencer platforms call trend_reports to get creative-Center trend reports & creative-guidance articles (official TikTok marketing insight…. | article_type, limit, page |
| locations | Supported markets for the `region` filter: ISO code + human country name (e.g. {code: 'DE', name: 'Germany'}), sorted by name. | Brand-monitoring teams call locations to get supported markets for the `region` filter. | none |
Call top_ads from your stack
curl -X POST https://api.reefapi.com/tiktok-creative-center/v1/top_ads \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"region":"US","period":"30"}'import requests
r = requests.post(
"https://api.reefapi.com/tiktok-creative-center/v1/top_ads",
headers={"x-api-key": REEF_KEY},
json={
"region": "US",
"period": "30"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/tiktok-creative-center/v1/top_ads", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"region": "US",
"period": "30"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.tiktok-creative-center.top_ads with {"region":"US","period":"30"}.Who uses this API and why
- Ad-intelligence tools call top_ads to find the highest-performing TikTok ads by industry and region.
- Creative teams use ad_detail and trend_reports to study winning hooks, formats and objectives.
- Competitor-research products use search_ads by brand to track a rival's live ad creative.
Questions developers ask before integrating
Is the cost field a dollar amount?
No, and treating it as one will give you nonsense. Across 20 ads pulled on 2026-08-27 the only values that ever appeared were 0, 1 and 2. It is a coarse spend bucket TikTok publishes instead of real ad spend, so the most you can read from it is relative scale. No action in this engine returns a currency amount for an ad.
What does ctr measure, and over what window?
Click-through rate as a percentage, over the period you asked for. Values measured on region US with period 30 ranged from 0.01 to 0.88, meaning 0.01 percent to 0.88 percent, not 1 percent to 88 percent. period accepts only 7, 30 and 180, and anything else falls back to 30, so the same ad will show different metrics depending on the window you request.
Does order_by cost work?
No. The spec lists it, but TikTok rejects it upstream. A live call with order_by "cost" on 2026-08-27 returned ok false with error.code UPSTREAM_HTTP and the message "Field validation for 'OrderBy' failed on the 'oneof' tag", retryable false. The three that do work are for_you, ctr and like. Since cost is only a 0 to 2 bucket anyway, pull with for_you or like and sort by cost yourself.
How do I turn industry_key into a readable category?
Call ad_filters and join on the label. An ad returns industry_key "label_20112000000"; ad_filters.industry returned 258 entries on 2026-08-27, each shaped {id, value, label, parent_id}, so label_20112000000 maps to a value name and parent_id points at its top-level vertical. There are 21 top-level verticals with round ids, such as 25000000000 Games, 14000000000 Beauty & Personal Care and 22000000000 Apparel & Accessories, and the rest are sub-categories under them.
Are the numbers absolute or a ranking?
Both, in different places. like, comment and share are absolute counts, and one measured ad carried 347,148 likes. There is no rank field: the order of the ads array is the ranking for whichever order_by you passed, and pagination.total_count tells you how large the ranked index is behind your filters, 178 for region US with period 30. So position in the array is the rank, and the metrics on it are real counts.
How many markets can I query?
The two taxonomy actions disagree, so use locations. On 2026-08-27 locations returned 73 countries, each as {id, code, name} with code being the value you pass as region, while ad_filters.country returned only 28. Pass a two-letter ISO code; an unsupported one falls back to US rather than erroring, so check that the region echoed back in meta matches what you asked for.
Why does page 2 come back empty?
Because TikTok serves a single ranked page per combination of region, period, filters and order_by. Asking for page 2 of the same combination returns nothing, no matter what total_count says. total_count 178 is the size of the index, not something you can page through. To see different ads, change order_by between for_you, ctr and like, change period between 7, 30 and 180, or add an industry or objective filter.
Why is brand_name so often null?
Because TikTok only attaches an advertiser name to some creatives. On 10 ads pulled with order_by ctr, 7 returned brand_name null and 3 named an advertiser. ad_title can also be an empty string on the same rows. Neither field is a reliable key, so use the ad id, which is a long numeric string such as 7664610922204889108, and feed that to ad_detail for the landing page and keyword list when they exist.
What is the TikTok Creative Center API?
TikTok Creative Center API is a ReefAPI endpoint group for tiktok creative center It returns live JSON through POST requests under /tiktok-creative-center/v1.
Is the TikTok Creative Center API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. TikTok Creative Center calls use the same shared credit balance as every other ReefAPI engine.
Do I need a TikTok Creative Center login or account?
No login to TikTok Creative Center is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the TikTok Creative Center data?
The page example is captured from a live top_ads call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the TikTok Creative Center API use?
TikTok Creative Center actions currently cost 1-3 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call TikTok Creative Center from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call tiktok-creative-center actions with the same key, credit pool and JSON envelope used by normal REST requests.