TikTok API endpoint
Lists Top Ads materials that TikTok Creative Center recommends as related to the ad with `material_id`. `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. The list can be empty for a valid id.
/tiktok/top-ads/recommendQuery parameters:
material_id: required. Top Ads material id.page: optional. Page number. Default: 1.limit: optional. Maximum number of ads to return. Default: 20. Maximum: 100.Notable response behavior:
materials array for valid material ids.| Field | In the sample |
|---|---|
| code | Has a value |
| msg | Has a value |
| request_id | Has a value |
| data.materials | Empty |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key required | ||
| material_id | string | Yes | Top Ads material id | 7631130810943897607 | |
| 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/recommend?material_id=7631130810943897607&page=1&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"code": 0,
"msg": "OK",
"data": {
"materials": []
}
}
}Request schema
No body schema
Response schema
#/definitions/populartrend.topAdsRecommendResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | popularTrend.TopAdsRecommendResp | No | ||||
| data.code | integer | No | ||||
| data.data | object | No | Ads related to the requested ad. | |||
| 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.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/recommend?material_id=7631130810943897607&page=1&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"