TikTok Shop Livestream Rank
12 credits/call
ae_tiktok_shop_livestream_rank
Retrieve TikTok Shop livestream rankings with country, time-window, creator, shop, product, category, keyword, and follower-range filters. Data is provided by Kalodata. Select `region` from this endpoint's supported country codes. The ranking date window is limited to 30 days. Use `sort_field` with a numeric response field and `ASC` or `DESC` direction; paginate with `page_number` and `page_size`. Revenue and price values are expressed in the selected `currency`.
12 credits/call
Pricing
12 credits/call
| Condition | Charge |
|---|---|
| Each call | 12 credits/call |
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
asc | boolean | No | Legacy ascending flag paired with `rank_field`. Default false (DESC). | — |
region | enum (US | BR | MX | ID | JP | MY | PH | SG | TH | VN | GB | ES | DE | FR | IT | PL | NL | BE | CZ | AT | GR | PT | HU | IE) | Yes | 数据所属国家/地区代码;请选择本接口支持的取值:US、BR、MX、ID、JP、MY、PH、SG、TH、VN、GB、ES、DE、FR、IT、PL、NL、BE、CZ、AT、GR、PT、HU、IE。 | — |
keyword | string | No | Keyword search | — |
shop_id | string | No | Restrict results to live streams promoting the given shop's products. | — |
currency | enum (CNY | USD | IDR | VND | THB | MYR | JPY | PHP | GBP | SGD | MXN | EUR | BRL | PLN | CZK | HUF) | Yes | Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL, PLN, CZK, HUF. | — |
language | enum (zh-CN | en-US | id-ID | th-TH | vi-VN | es-ES | ja-JP | pt-BR | ko-KR | fr-FR | de-DE | pl-PL | nl-NL | cs-CZ | el-GR | hu-HU | pt-PT | it-IT) | Yes | Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR, de-DE, pl-PL, nl-NL, cs-CZ, el-GR, hu-HU, pt-PT, it-IT. | — |
page_size | integer | No | Page size. Maximum 100 records per query. Default 10. | 10 |
creator_id | string | No | Restrict results to live streams hosted by the given creator. | — |
date_range | string | Yes | 排行榜查询日期范围,最多 30 天。可使用支持的相对日期范围,或日期区间格式 yyyy-MM-dd~yyyy-MM-dd;自然日期区间不可超过 30 天。 | — |
product_id | string | No | Restrict results to live streams mounting the given product. | — |
rank_field | string | No | Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set. | — |
sort_field | object | Yes | 排序设置。field 指定响应中的数值型字段,type 指定 ASC(升序)或 DESC(降序)。 | — |
sort_field.type | enum (ASC | DESC) | No | 排序方向:ASC(升序)或 DESC(降序)。 | — |
sort_field.field | string | No | 排序字段名称;使用此接口响应中提供的数值型字段。 | — |
page_number | integer | No | Page number, starting at 1. | 1 |
category_ids | array | No | Restrict results to live streams in the given category IDs. | — |
followers_range | string | No | Follower count range of the live stream host. Also supports `<100` / `>10000` forms. | — |
Invocation example
Copy the request and explore its response example.
POST
/agent-api/v1/tool/executeX-Api-KeyRequest coderequest.sh
curl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_tiktok_shop_livestream_rank' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"currency": "IDR",
"date_range": "2026-11-02~2026-11-11",
"language": "zh-CN",
"page_number": 1,
"page_size": 3,
"product_id": "1738180406312470332",
"region": "ID",
"sort_field": {
"field": "revenue",
"type": "DESC"
}
}
}'Response exampleresponse.json
{
"cached": null,
"code": null,
"data": [
{
"creator_handle": "huaweimobileid",
"creator_id": "7213592961815430170",
"livestream_duration": 10758,
"livestream_end_time": 1793735992000,
"livestream_id": "7703991053111659282",
"livestream_start_time": 1793725234000
}
],
"message": null,
"success": true
}This example shows part of the response. Copied content is valid JSON.

