TikTok API endpoint
Returns high-performing auction ads from TikTok Creative Center. The service defaults `period` to 30, `page` to 1, `limit` to 20, and `order_by` to `for_you`. Use `/tiktok/top-ads/filters` for dynamic enum values and static enums for order, duration, likes, and ad format.
/tiktok/top-ads/listQuery parameters:
period: optional. Lookback period in days. Default: 30. Allowed values: 7, 30, 180.page: optional. Page number. Default: 1.limit: optional. Maximum number of ads to return. Default: 20. Maximum: 100.order_by: optional. Sort order. Default: for_you. Allowed values: for_you, impression, ctr, play_2s_rate, play_6s_rate, cvr, like.country_code: optional. Country code or comma-separated country codes from /api/v1/tiktok/top-ads/filters. Example: US.keyword: optional. Brand or product keyword search.industry: optional. Industry filter id or comma-separated ids from /api/v1/tiktok/top-ads/filters.objective: optional. Objective filter id or comma-separated ids from /api/v1/tiktok/top-ads/filters.ad_language: optional. Ad language id or comma-separated ids from /api/v1/tiktok/top-ads/filters.pattern_label: optional. Pattern label id or comma-separated ids from /api/v1/tiktok/top-ads/filters.duration: optional. Video duration bucket. Allowed values: time-2 (<10s), time-3 (10-20s), time-4 (20-30s), time-5 (30-40s), time-6 (40-50s), time-7 (>50s).like: optional. Like percentile bucket id or comma-separated ids. Allowed values: 1 (Top 1~20%), 2 (Top 21~40%), 3 (Top 41~60%), 4 (Top 61~80%), 5 (Top 81~100%).ad_format: optional. Ad format id. Allowed values: 1 (Spark ads), 2 (Non-Spark ads).Notable response behavior:
country_code, industry, objective, ad_language, pattern_label, and period come from /api/v1/tiktok/top-ads/filters.docs/tiktok-top-ads-enums.md.| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| ad_title | 1 | |
| cost | 1 | 0 |
| ctr | 1 | 0.56 |
| favorite | 1 | true in 0 of 1 |
| id | 1 | |
| industry_key | 1 | |
| is_search | 1 | true in 1 of 1 |
| like | 1 | 2 |
| objective_key | 1 | |
| video_info | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key required | ||
| period | integer | No | Lookback period in days Allowed values: 7, 30, 180. | ||
| page | integer | No | Page number Minimum: 1. | ||
| limit | integer | No | Maximum number of ads to return Maximum: 100. | ||
| order_by | string | No | Sort order Allowed values: for_you, impression, ctr, play_2s_rate, play_6s_rate, cvr, like. | ||
| country_code | string | No | Country code or comma-separated country codes from /tiktok/top-ads/filters | US | |
| keyword | string | No | Brand or product keyword search | coffee | |
| industry | string | No | Industry filter id or comma-separated ids from /tiktok/top-ads/filters | 23118000000 | |
| objective | string | No | Objective filter id or comma-separated ids from /tiktok/top-ads/filters | 3 | |
| ad_language | string | No | Ad language id or comma-separated ids from /tiktok/top-ads/filters | en | |
| pattern_label | string | No | Pattern label id or comma-separated ids from /tiktok/top-ads/filters | 10100100000 | |
| duration | string | No | Video duration bucket Allowed values: time-2, time-3, time-4, time-5, time-6, time-7. | ||
| like | string | No | Like percentile bucket id or comma-separated ids Allowed values: 1, 2, 3, 4, 5. | ||
| ad_format | string | No | Ad format id Allowed values: 1, 2. |
curl -X GET "https://api.crawlora.net/api/v1/tiktok/top-ads/list?period=7&page=1&limit=10&order_by=for_you&keyword=coffee&duration=time-2&like=1&ad_format=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"code": 0,
"msg": "OK",
"data": {
"materials": [
{
"id": "7631130810943897607",
"ad_title": "Example ad",
"like": 120,
"ctr": 0.42
}
],
"pagination": {
"has_more": true,
"page": 1,
"size": 20,
"total_count": 381
}
}
}
}Request schema
No body schema
Response schema
#/definitions/populartrend.topAdsListResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | popularTrend.TopAdsListResp | No | ||||
| data.code | integer | No | ||||
| data.data | object | No | Page of top ads with its paging information. | |||
| data.data.materials | array | No | ||||
| data.data.materials[].ad_title | string | No | Title of the ad. | |||
| data.data.materials[].brand_name | string | No | Name of the advertiser brand. | |||
| data.data.materials[].comment | integer | No | Number of comments on the ad. | |||
| data.data.materials[].cost | integer | No | Cost figure for the ad as TikTok Creative Center reports it. | |||
| data.data.materials[].country_code | array | No | Country codes the ad runs in. | |||
| data.data.materials[].ctr | number | No | Click-through rate of the ad as TikTok Creative Center reports it. | |||
| data.data.materials[].favorite | boolean | No | Whether the ad is marked as a favorite. | |||
| data.data.materials[].has_summary | boolean | No | Whether TikTok has an ad summary available for the ad. | |||
| data.data.materials[].highlight | string | No | Highlight note TikTok attaches to the ad. | |||
| data.data.materials[].highlight_text | string | No | Text shown for the ad's highlight. | |||
| data.data.materials[].id | string | No | Top Ads material id. Use it with the detail, analysis and recommend endpoints. | |||
| data.data.materials[].industry_key | string | No | Key of the industry the ad is classified under. | |||
| data.data.materials[].is_search | boolean | No | Search flag TikTok sets on the ad. | |||
| data.data.materials[].keyword_list | array | No | Keywords associated with the ad. | |||
| data.data.materials[].landing_page | string | No | URL of the ad's landing page. | |||
| data.data.materials[].like | integer | No | Number of likes on the ad. | |||
| data.data.materials[].objective_key | string | No | Key of the campaign objective of the ad. | |||
| data.data.materials[].objectives | array | No | Campaign objectives of the ad, each with its id, value and label. | |||
| data.data.materials[].objectives[].has_conversion | boolean | No | Whether the objective is one that tracks conversions. Only set on objective options. | |||
| data.data.materials[].objectives[].id | object | No | Filter option id in TikTok's own format, a string or a number depending on the filter. | |||
| data.data.materials[].objectives[].label | string | No | Label key TikTok uses for the option. | |||
| data.data.materials[].objectives[].parent_id | object | No | Id of the parent option, for example the top-level industry of a sub-industry. | |||
| data.data.materials[].objectives[].value | string | No | Display value of the option, always returned as a string. | |||
| data.data.materials[].pattern_label | array | No | Creative pattern labels assigned to the ad. | |||
| data.data.materials[].pattern_label[].has_conversion | boolean | No | Whether the objective is one that tracks conversions. Only set on objective options. | |||
| data.data.materials[].pattern_label[].id | object | No | Filter option id in TikTok's own format, a string or a number depending on the filter. | |||
| data.data.materials[].pattern_label[].label | string | No | Label key TikTok uses for the option. | |||
| data.data.materials[].pattern_label[].parent_id | object | No | Id of the parent option, for example the top-level industry of a sub-industry. | |||
| data.data.materials[].pattern_label[].value | string | No | Display value of the option, always returned as a string. | |||
| data.data.materials[].share | integer | No | Number of shares of the ad. | |||
| data.data.materials[].source | string | No | Source label of the ad as TikTok Creative Center shows it. | |||
| data.data.materials[].source_key | integer | No | Numeric key of the ad's source. | |||
| data.data.materials[].video_info | object | No | Video file details of the ad. | |||
| data.data.materials[].video_info.cover | string | No | URL of the video cover image. | |||
| data.data.materials[].video_info.duration | number | No | Video length in seconds. | |||
| data.data.materials[].video_info.height | integer | No | Video height as TikTok reports it. | |||
| data.data.materials[].video_info.vid | string | No | TikTok video id. | |||
| data.data.materials[].video_info.video_url | object | No | Video file URLs keyed by resolution label, for example `720p`. | |||
| data.data.materials[].video_info.width | integer | No | Video width as TikTok reports it. | |||
| data.data.materials[].voice_over | boolean | No | Whether the ad video has a voice-over. | |||
| data.data.pagination | popularTrend.TopAdsPagination | No | ||||
| data.data.pagination.has_more | boolean | No | Whether more pages of ads are available. | |||
| data.data.pagination.page | integer | No | Page number returned. | |||
| data.data.pagination.size | integer | No | Number of ads per page. | |||
| data.data.pagination.total | integer | No | Total number of matching ads. Set on spotlight responses. | |||
| data.data.pagination.total_count | integer | No | Total number of matching ads. Set on list responses. | |||
| data.msg | string | No | ||||
| data.request_id | string | No | Request id returned by TikTok Creative Center. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid input | #/definitions/app.Response |
| 429 | Rate limit exceeded | #/definitions/app.Response |
| 500 | Internal server error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/tiktok/top-ads/list?period=7&page=1&limit=10&order_by=for_you&keyword=coffee&duration=time-2&like=1&ad_format=1" \
-H "x-api-key: $CRAWLORA_API_KEY"