TikTok Ads Get Top Contents List
### Purpose Retrieve the Creative Center Top Contents ranking for a selected period and country, useful for trend discovery, content research, and creative inspiration. The ranking corpus contains 100 videos; `page` and `limit` determine which portion is returned. ### Input Pass a JSON `request_body` with the required `period_end_timestamp`: a nonzero 10-digit Unix timestamp in seconds generated for the target ranking date. For `period_dimension=1` (weekly), use Sunday 00:00 UTC; for `period_dimension=3` (daily) or `5` (long-period), use a past date. Optional fields: - `period_dimension`: `1` weekly, `3` daily (default), or `5` long-period. - `country_code`: country/region code (default `US`). Some regions may have no ranking data. - `content_label_ids`: comma-separated content label IDs; empty means all categories. - `order_by_metric`: `1` views (default), `2` engagement rate, or `3` six-second view-through rate. - `organic_only`: return only organic-traffic content (default `false`). - `page`: page number (default `1`). - `limit`: items per page (default `20`, maximum `100`). - `cookie`: optional custom cookie string. ### Output The response data includes `entityInfos`, a list of ranked videos, and `pagination`. Video entries can include item details such as title, creation time, cover and video URLs, performance metrics such as views, engagement rate, and six-second view-through rate, author information and follower metrics, and content tags. An empty `entityInfos` may be a normal result when the selected region is not covered. A page beyond the 100-item ranking may return an out-of-range error.
Pricing
| Condition | Charge |
|---|---|
| Each call | 2.07 credits/call |
2.07 credits/call Charges are per query. A successful query is billed even if it returns no results.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
request_body | object | Yes | 请求体对象,包含榜单查询条件;请按已定义的对象字段提供周期结束时间戳及可选筛选和分页参数。 | — |
request_body.page | integer | No | 页码/Page number | 1 |
request_body.limit | integer | No | 每页数量,最大100/Items per page, max 100 | 20 |
request_body.cookie | string | No | 自定义Cookie字符串(可选)/Custom Cookie string (optional) | — |
request_body.country_code | string | No | 国家/地区代码/Country code | US |
request_body.organic_only | boolean | No | 是否仅看自然流量内容/Organic content only | false |
request_body.order_by_metric | integer | No | 排序指标:1 播放量 2 互动率 3 6秒完播率/Order by metric | 1 |
request_body.period_dimension | integer | No | 榜单周期:1/3/5 /Period dimension | 3 |
request_body.content_label_ids | string | No | 内容分类ID,多个用逗号分隔,空为全部/Content label IDs, comma separated | "" |
request_body.period_end_timestamp | integer | Yes | 调用方需根据目标榜单日期自行生成结束时间戳(10位 Unix 秒级),例如 1785024000;请勿传 0,否则会返回空结果/The caller must generate this 10-digit Unix timestamp in seconds from the target ranking date, for example 1785024000; do not pass 0 because it returns an empty result | — |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_tiktok_ads_get_top_contents_list' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"request_body": {
"content_label_ids": "18100000000,21104000000,21999000000,21102000000,18999000000",
"country_code": "TH",
"limit": 50,
"order_by_metric": 1,
"page": 1,
"period_dimension": 1,
"period_end_timestamp": 1794096000
}
}
}'{
"code": 200,
"data": {
"BaseResp": {
"StatusCode": 0,
"StatusMessage": ""
},
"entityInfos": []
},
"docs": "https://api.tikhub.io/#/TikTok-Ads-API/get_top_contents_list_api_v1_tiktok_ads_get_top_contents_list_post",
"message": "Request successful. This request will incur a charge.",
"message_zh": "请求成功,本次请求将被计费。",
"params": {}
}This example shows part of the response. Copied content is valid JSON.

