# 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. **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. 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. |

## Code example

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

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