TikTok Ads Get Top Contents List

2.07 credits/call
ae_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.

VideoSocial
2.07 credits/call

Pricing

2.07 credits/call
ConditionCharge
Each call2.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.

ParameterTypeRequiredDescriptionDefault
request_bodyobjectYes请求体对象,包含榜单查询条件;请按已定义的对象字段提供周期结束时间戳及可选筛选和分页参数。—
request_body.pageintegerNo页码/Page number1
request_body.limitintegerNo每页数量,最大100/Items per page, max 10020
request_body.cookiestringNo自定义Cookie字符串(可选)/Custom Cookie string (optional)—
request_body.country_codestringNo国家/地区代码/Country codeUS
request_body.organic_onlybooleanNo是否仅看自然流量内容/Organic content onlyfalse
request_body.order_by_metricintegerNo排序指标:1 播放量 2 互动率 3 6秒完播率/Order by metric1
request_body.period_dimensionintegerNo榜单周期:1/3/5 /Period dimension3
request_body.content_label_idsstringNo内容分类ID,多个用逗号分隔,空为全部/Content label IDs, comma separated""
request_body.period_end_timestampintegerYes调用方需根据目标榜单日期自行生成结束时间戳(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.

POST/agent-api/v1/tool/executeX-Api-Key
Request coderequest.sh
curl --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
    }
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "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.