# TikTok Ads Top API (https://www.socialcrawl.dev/platforms/tiktok/ads-top)

> Returns TikTok's own leaderboard of top-performing ads for a market and time window, with the performance signals TikTok publishes and nothing else does: `ext.ad.ctr` is the click-through rate, `ext.ad.rank` is the ad's position on the board, `ext.ad.cost_score` and `ext.ad.like_tier` are TikTok's own banded cost and engagement tiers, and `engagement.likes` is the real like count. Each row carries the ad's video at `content.media_urls` (720p, with 540p and 360p renditions on `ext.ad`), the cover image, the duration, the advertiser at `author.username`, and the campaign objective and industry at `ext.ad.objective` / `ext.ad.industry`. **This is a different surface from `/v1/tiktok/adlibrary/search`.** That endpoint reads the EU Commercial Content Library, which carries who an ad was targeted at across 33 EU/EEA countries but publishes no performance data; this one reads the global Creative Center board across 24 markets including the US, Korea, Japan and Brazil, and publishes performance but no targeting. Use this one to find creative that worked, and that one to find who an advertiser bought. **There is no publish date**: TikTok does not attach one to the board, so `published_at` is null on every row rather than filled with the time you called. `brandName` is absent on roughly half of live rows because TikTok attributes some top ads to no brand, so `author.username` is null there too. **2-second and 6-second view rates:** `order_by=play_2s_rate` and `order_by=play_6s_rate` rank the board by TikTok's own view-rate figures, which TikTok uses for the ranking and does not publish as numbers. What TikTok publishes for each ad is its second-by-second audience retention curve: send `include=retention` and every row carries `ext.ad.retention` (one `{second, value}` point per second, the share of viewers still watching, 1 at second 0), with `ext.ad.retention_2s` and `ext.ad.retention_6s` the points at second 2 and second 6 (null when the ad is shorter than that). These are TikTok's curve values, not the figure it sorts by, so the board's order and the 6-second points do not always agree. `include=retention` reads up to 20 ads per call, usually takes 20 to 35 seconds, and cannot be combined with `keyword` or `industry`. **Pricing is metered at 1 credit per ad RETURNED, with a minimum of 10** — the board is served in blocks of ten, so a smaller `limit` still costs ten.

TL;DR: `GET /v1/tiktok/ads/top` costs 1 credit per ad returned, minimum 10 credits. A limit of 20 holds 20 credits and settles down to the number of ads that actually came back; a filter combination with no board costs nothing. With include=retention, 2 credits per ad that carries a retention curve (minimum 20), and 1 per ad TikTok serves no curve for. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `country` | no | Creative Center market to read the board for. Defaults to US. This is the market the ads ran in, not the language they are in. (US \| CA \| MX \| BR \| GB \| DE \| FR \| IT \| ES \| NL \| PL \| SE \| TR \| SA \| AE \| AU \| JP \| KR \| ID \| TH \| VN \| MY \| PH \| SG) |
| `period` | no | Lookback window in days: 7, 30 or 180. Defaults to 30. A longer window is a different board, not more rows. (7 \| 30 \| 180) |
| `order_by` | no | How TikTok ranks the board: for_you (TikTok's own blend, the default), ctr, impression, like, cvr, play_2s_rate or play_6s_rate. (for_you \| impression \| ctr \| play_2s_rate \| play_6s_rate \| cvr \| like) |
| `ad_format` | no | Restrict to Spark ads (ads boosted from an organic post) or Non-Spark ads. Defaults to all. (All ad types \| Spark ads \| Non-Spark ads) |
| `ad_language` | no | Filter by the language of the ad copy. (en \| ja \| zh \| vi \| th \| pt \| id) |
| `like_tier` | no | TikTok's engagement percentile band, 1 (top) to 5. Use it to read further down the ranking without raising limit. (1 \| 2 \| 3 \| 4 \| 5) |
| `industry` | no | Creative Center sub-category label, for example 'Skincare' or 'Cosmetics'. Use a sub-category, not a top-level group: the board returns nothing for the broad groups such as 'Financial Services' or 'Education'. Omit for all industries. |
| `keyword` | no | Search the board by brand or product keyword. |
| `limit` | no | How many ads to return, 1-100, default 20. The board is served in blocks of ten, so any limit below 10 still costs 10 credits. With include=retention, 1-20. |
| `include` | no | Send `retention` to add each ad's second-by-second audience retention curve (`ext.ad.retention`) and its points at second 2 and second 6 (`ext.ad.retention_2s`, `ext.ad.retention_6s`). 2 credits per ad that carries a curve, minimum 20; up to 20 ads per call; usually 20 to 35 seconds; not combinable with keyword or industry. |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/ads/top" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### What does the TikTok Ads Top API return?

Returns TikTok's Creative Center leaderboard of top-performing ads for a market and time window, each with click-through rate, board rank, like count, industry, objective, and the ad video. The response uses the same JSON envelope as every SocialCrawl endpoint, with the data, credits_used and request_id fields.

### When should I use the TikTok Ads Top endpoint?

Use it to find ad creative that actually performed. It is one window with no cursor, so set limit for depth and change country, period, or order_by for a different board.

### How much does the TikTok Ads Top API cost?

The price depends on the request, from 10 to 100 credits per call. Every new account gets 100 free credits. Credits for failed or empty calls are refunded automatically, and there is no subscription.

### What parameters does the TikTok Ads Top API need?

No parameter is required, so the bare URL works. It also accepts 12 optional parameters, all listed on this page. The optional parameter to try first is country (Results for one country).

### How do I call the TikTok Ads Top API?

Send a GET request to https://www.socialcrawl.dev/v1/tiktok/ads/top with your API key in the x-api-key header. An Authorization: Bearer header works too.

See the full TikTok API: https://www.socialcrawl.dev/platforms/tiktok

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- What does the SocialCrawl TikTok Ads Top API return?
- How do I get TikTok Ads Top data with the SocialCrawl API?