# TikTok Creative Center API — TikTok ad-spy & creative intelligence: top-performing Top Ads by region/industry/objective, full ad detail (CTR, spend, likes, shares, comments, landing page, video renditions), keyword ad search, the live filter taxonomy (81 countries / 258 industries / objectives / languages) and official creative trend reports — the PiPiADS / Minea / AdSpy data as a raw JSON API

> 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.
> ReefAPI engine `tiktok-creative-center` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/tiktok-creative-center/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /tiktok-creative-center/v1/top_ads — 3 credits
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.

**Parameters:**
- `region` (string, optional, default "US") — Two-letter ISO country code to scope the ads to a market. Common: US, GB, DE, FR, ES, IT, JP, KR, BR, MX, ID, TH, VN, TR, SA, AE, IN, CA, AU. Default US. Call the `locations` action for the full 73-market list (each {code, name}); unsupported codes fall back to US.
- `period` (enum, optional, default "30") — Trailing window the ad metrics are measured over, in days. Only 7, 30 or 180 are accepted by TikTok (any other value falls back to 30). Shorter = fresher/breakout ads, longer = established performers. [one of: 7, 30, 180]
- `order_by` (enum, optional, default "for_you") — How the returned ads are ranked: 'for_you' = TikTok's recommended mix, or sort by 'ctr' (click-through rate), 'like' (most liked) or 'cost' (highest spend). Each call returns one ranked page of up to 20. [one of: for_you, ctr, like, cost]
- `industry` (string, optional) — Numeric industry id to filter ads by — one of the 21 top-level verticals listed in allowed_values (e.g. 25000000000 = Games, 14000000000 = Beauty & Personal Care, 22000000000 = Apparel & Accessories). Sub-category ids are also accepted; browse the full 258-entry taxonomy (with parent_id hierarchy) via the `ad_filters` action. [one of: 10000000000, 11000000000, 12000000000, 13000000000, 14000000000, 15000000000, 16000000000, 17000000000, 18000000000, 19000000000, 20000000000, 21000000000, 22000000000, 23000000000, 24000000000, 25000000000, 26000000000, 27000000000, 28000000000, 29000000000, 30000000000]
- `objective` (string, optional) — Campaign objective filter (id or name: Traffic, Conversions, App Installs, Video Views, Reach, Lead Generation, Product Sales). [one of: 1, 2, 3, 4, 5, 8, 15]
- `ad_language` (string, optional) — Ad-language filter, e.g. language_en / language_es / language_de (see ad_filters.ad_language for the 16 supported values).
- `limit` (integer, optional, default 20) — How many ads to return (1-20; TikTok hard-caps a page at 20). The response includes pagination.total_count = the full size of the ranked index for your filters.
- `page` (integer, optional, default 1) — Result page. NOTE: TikTok's Top-Ads endpoint serves a single ranked page per (region/period/filter/order_by) combination — page>1 returns empty. To see different ads, vary order_by (ctr/like/cost), period, industry or objective rather than the page number.

**Returns:** ads[]{id, ad_title, brand_name, ctr, like, cost, industry_key, objective_key, is_search, video{vid, duration, cover_url, width, height, video_urls{360p,480p,540p,720p,1080p}}} + pagination{page, size, total_count, has_more}

**Example request body:**
```json
{
  "region": "US",
  "period": "30"
}
```

### POST /tiktok-creative-center/v1/ad_detail — 3 credits
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).

**Parameters:**
- `ad_id` (string, required) — Creative/material id (the `id` field of a top_ads result).

**Returns:** ad{id, ad_title, brand_name, ctr, like, comment, share, cost, country_code, landing_page, keyword_list[], objectives[], highlight_text, pattern_label, source, source_key, voice_over, video{vid, duration, cover_url, video_urls{360p..1080p}}}

### POST /tiktok-creative-center/v1/search_ads — 3 credits
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.

**Parameters:**
- `keyword` (string, required) — Search term to match against the Top-Ads index.
- `region` (string, optional, default "US") — Two-letter ISO country code to scope the ads to a market. Common: US, GB, DE, FR, ES, IT, JP, KR, BR, MX, ID, TH, VN, TR, SA, AE, IN, CA, AU. Default US. Call the `locations` action for the full 73-market list (each {code, name}); unsupported codes fall back to US.
- `period` (enum, optional, default "30") — Trailing window the ad metrics are measured over, in days. Only 7, 30 or 180 are accepted by TikTok (any other value falls back to 30). Shorter = fresher/breakout ads, longer = established performers. [one of: 7, 30, 180]
- `limit` (integer, optional, default 20) — How many ads to return (1-20; TikTok hard-caps a page at 20). The response includes pagination.total_count = the full size of the ranked index for your filters.
- `page` (integer, optional, default 1) — Result page. NOTE: TikTok's Top-Ads endpoint serves a single ranked page per (region/period/filter/order_by) combination — page>1 returns empty. To see different ads, vary order_by (ctr/like/cost), period, industry or objective rather than the page number.

**Returns:** ads[]{id, ad_title, brand_name, ctr, like, cost, industry_key, objective_key, is_search, video{vid, duration, cover_url, width, height, video_urls{360p,480p,540p,720p,1080p}}} + pagination{page, size, total_count, has_more} + keyword, search_id

### POST /tiktok-creative-center/v1/ad_filters — 1 credit
The live filter taxonomy used by top_ads: full country (81), industry (258), objective (7), ad_language (16), pattern_label and period value lists.

**Parameters:** none

**Returns:** filters{country[], industry[], objective[], ad_language[], pattern_label[], period[]} — each entry {id, value, label}

### POST /tiktok-creative-center/v1/query_suggestions — 1 credit
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.

**Parameters:**
- `limit` (integer, optional, default 20) — How many suggestions (1-50).

**Returns:** suggestions[] (trending query strings)

### POST /tiktok-creative-center/v1/trend_reports — 1 credit
Creative-Center trend reports & creative-guidance articles (official TikTok marketing insight content).

**Parameters:**
- `article_type` (enum, optional, default "trends") — Which Creative-Center article stream to return. [one of: trends, guidance, 1, 2]
- `limit` (integer, optional, default 10) — Articles (1-50).
- `page` (integer, optional, default 1) — Result page. NOTE: TikTok's Top-Ads endpoint serves a single ranked page per (region/period/filter/order_by) combination — page>1 returns empty. To see different ads, vary order_by (ctr/like/cost), period, industry or objective rather than the page number.

**Returns:** articles[]{article_id, title, author, tag, cover_url, publish_time, url_title, description}

**Example request body:**
```json
{
  "article_type": "trends"
}
```

### POST /tiktok-creative-center/v1/locations — 1 credit
Supported markets for the `region` filter: ISO code + human country name (e.g. {code: 'DE', name: 'Germany'}), sorted by name.

**Parameters:** none

**Returns:** countries[]{id, code, name} — code is the value to pass as `region`

## More
- Try it live, no code: https://reefapi.com/playground?engine=tiktok-creative-center
- Human docs page: https://reefapi.com/docs/tiktok-creative-center
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt