TikTok API endpoint
Returns the detail-page interactive time analysis chart and percentile for a Top Ads material. Metric values are `retain_ctr` (CTR), `retain_cvr` (CVR), `click_cnt` (Clicks), `convert_cnt` (Conversion), and `play_retain_cnt` (Remain).
/tiktok/top-ads/analysisReturns the detail-page interactive time analysis chart and percentile for one TikTok Creative Center Top Ads material.
Query parameters:
material_id: required. Top Ads material id. Example: 7130614705291427842.metric: optional. Default: retain_ctr. Allowed values: retain_ctr (CTR), retain_cvr (CVR), click_cnt (Clicks), convert_cnt (Conversion), play_retain_cnt (Remain).period_type: optional. Percentile lookback period in days. Default: 7. Allowed values: 7, 30, 180.Notable response behavior:
/top_ads/keyframe endpoint.percentile value comes from TikTok's public /top_ads/percentile endpoint and uses the matching percentile metric for the requested tab.metric and period_type are listed in docs/tiktok-top-ads-enums.md.| Field | Filled in, of 18 checked | Values in the sample |
|---|---|---|
| second | 18 | 0 to 17, median 8 |
| value | 18 | 0 to 1, median 0.09 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key required | ||
| material_id | string | Yes | Top Ads material id | 7130614705291427842 | |
| metric | string | No | Interactive time analysis metric Allowed values: retain_ctr, retain_cvr, click_cnt, convert_cnt, play_retain_cnt. | ||
| period_type | integer | No | Percentile lookback period in days Allowed values: 7, 30, 180. |
curl -X GET "https://api.crawlora.net/api/v1/tiktok/top-ads/analysis?material_id=7130614705291427842&metric=retain_ctr&period_type=7" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"code": 0,
"msg": "OK",
"data": {
"metric": "retain_cvr",
"metric_label": "CVR",
"percentile_metric": "time_attr_conversion_rate_percentile",
"period_type": 7,
"analysis": [
{
"second": 0,
"value": 0.12
}
],
"duration": 30,
"highlight": [
3,
8,
15
],
"percentile": 0.81
}
}
}Request schema
No body schema
Response schema
#/definitions/populartrend.topAdsAnalysisResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | popularTrend.TopAdsAnalysisResp | No | ||||
| data.code | integer | No | ||||
| data.data | object | No | Time analysis of the ad for the chosen metric, with its percentile, chart points and highlighted seconds. | |||
| data.data.analysis | array | No | ||||
| data.data.analysis[].second | integer | No | Second of the ad video the point refers to. | |||
| data.data.analysis[].value | number | No | Value of the selected metric at that second. | |||
| data.data.duration | number | No | ||||
| data.data.highlight | array | No | ||||
| data.data.metric | string | No | ||||
| data.data.metric_label | string | No | ||||
| data.data.percentile | number | No | ||||
| data.data.percentile_data | object | No | ||||
| data.data.percentile_metric | string | No | ||||
| data.data.period_type | integer | No | ||||
| 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/analysis?material_id=7130614705291427842&metric=retain_ctr&period_type=7" \
-H "x-api-key: $CRAWLORA_API_KEY"