Douyin Xingtu Get Ranking List Data

4.13 credits/call
ae_douyin_xingtu_get_ranking_list_data

## Purpose Retrieve creator ranking data for a selected category, ranking type, reporting date, and weekly or monthly period. Supported contexts include short-video business rankings, short-video content rankings, and live-stream creator rankings. ## Inputs All five inputs are optional and have fixed defaults: - `code` (integer, default `1`): ranking type. Short-video business codes: `1` brand preferred, `2` A3 seeding, `3` search after viewing, `4` e-commerce, `5` ad traffic, `6` high potential. Short-video content codes: `17` follower-growth dark horses and `18` top must-pick creators. For live-stream creator types with `version="base"`: `23` gaming, `30` other, `37` e-commerce. Live ranking-type codes: `23` gaming-industry brand preferred, `24` non-gaming-industry brand preferred, `25` component clicks, `26` download conversions, `27` lead collection, `28` ad traffic, `29` high potential. Code meanings depend on the ranking context; in particular, `23` has more than one documented meaning. - `qualifier` (string, default `"1901"`): category ID obtained from the ranking catalog. Use the ID corresponding to the intended ranking category. - `version` (string, default `"flow_split"`): `flow_split` is the default for short-video rankings; `base` is commonly used for live rankings. - `period` (integer, default `30`): `7` for weekly rankings or `30` for monthly rankings. - `date` (string, default `"20260131"`): reporting date in `YYYYMMDD` format. Specify the date you want; the fixed default is not the current date. ## Result Returns a response object with the requested ranking payload in `data`, which may be null, and a response status in `code`. The response status code is distinct from the input ranking-type code. The available schema does not define individual ranking-entry fields or metrics. Example inputs: `code=1`, `qualifier="1901"`, `version="flow_split"`, `period=30`, `date="20260131"`.

Social
4.13 credits/call

Pricing

4.13 credits/call
ConditionCharge
Each call4.13 credits/call

A fixed charge of 4.13 credits applies per 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
codeintegerNo榜单类型代码/Ranking type code1
datestringNo统计日期,格式YYYYMMDD/Date, format YYYYMMDD20260131
periodintegerNo统计周期,7=周榜,30=月榜/Period, 7=weekly, 30=monthly30
versionstringNo版本/Versionflow_split
qualifierstringNo榜单分类ID,从get_ranking_list_catalog获取/Category qualifier_id1901

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_douyin_xingtu_get_ranking_list_data' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "code": 1,
    "date": "20261101",
    "period": 7,
    "qualifier": "1904",
    "version": "flow_split"
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "code": 200,
  "data": {
    "authors": [
      {
        "attribute_datas": {
          "author_id": "6751190073166790663",
          "author_status": "1",
          "avatar_uri": "https://p26.douyinpic.com/aweme/1080x1080/aweme-avatar/tos-cn-avt-0015_bfe8b8551c35036f4183abdd07e6da6a.jpeg?from=3782654143",
          "city": "杭州市",
          "core_user_id": "104934349824",
          "cpm": "126873"
        },
        "is_new": true,
        "items": [
          {
            "item_id": "7683366672215837988",
            "video_tag": 3,
            "vv": 11366678
          }
        ],
        "old_rank": "0",
        "rank": "1",
        "score": 0.578125
      }
    ]
  },
  "docs": "https://api.tikhub.io/#/Douyin-Xingtu-V2-API/get_ranking_list_data_api_v1_douyin_xingtu_v2_get_ranking_list_data_get",
  "message": "Request successful. This request will incur a charge."
}

This example shows part of the response. Copied content is valid JSON.