TikTok API endpoint
Lists the Top Ads Spotlight materials that TikTok Creative Center hand-picks. `page` starts at 1; `limit` defaults to 20 and is capped at 100. Each ad has its title, brand, likes, comments, shares, CTR, objectives and video info. `data.pagination` gives the page, size, total and `has_more`.
/tiktok/top-ads/spotlightQuery parameters:
page: optional. Page number. Default: 1.limit: optional. Maximum number of ads to return. Default: 20. Maximum: 100.Notable response behavior:
total rather than total_count in the upstream payload.| Field | Filled in, of 5 checked | Values in the sample |
|---|---|---|
| cost | 5 | 1 to 2, median 2 |
| ctr | 5 | 0.13 to 0.21, median 0.15 |
| favorite | 5 | true in 0 of 5 |
| highlight | 5 | median 218 characters |
| id | 5 | |
| like | 5 | 77 to 36,951, median 5,580 |
| video_info | 5 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key required | ||
| page | integer | No | Page number Minimum: 1. | ||
| limit | integer | No | Maximum number of ads to return Maximum: 100. |
curl -X GET "https://api.crawlora.net/api/v1/tiktok/top-ads/spotlight?page=1&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"code": 0,
"msg": "OK",
"data": {
"materials": [
{
"id": "7200915172051156993",
"highlight": "Creative note",
"like": 86410,
"ctr": 0.25
}
],
"pagination": {
"page": 2,
"size": 20,
"total": 39,
"has_more": false
}
}
}
}Request schema
No body schema
Response schema
#/definitions/populartrend.topAdsSpotlightResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | popularTrend.TopAdsSpotlightResp | No | ||||
| data.code | integer | No | ||||
| data.data | object | No | Page of spotlight 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/spotlight?page=1&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"