TikTok Shop Video Rank
Retrieve TikTok Shop video rankings and filter results by creator, product, shop, category, engagement, revenue, or other supported criteria. Data is provided by Kalodata and covers multiple countries; set `region` to the country you want to query. **`date_range`**: this ranking is limited to a maximum 30-day window. The documented choices are `lastDay`, `last7Day`, `last30Day`, a `yyyy-MM-dd~yyyy-MM-dd` date range spanning no more than 30 days, or a `yyyy-MM` month. **`sort_field`**: provide an object with `field` and `type` (`ASC` or `DESC`). The documented default is `revenue` descending. The endpoint also returns video performance fields such as views, revenue growth rate, ad ROAS, video ID and title.
Pricing
| Condition | Charge |
|---|---|
| Each call | 12 credits/call |
Fixed charge: 12 credits per call.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
asc | boolean | No | Legacy ascending flag. For ordering, use the `sort_field` object. | — |
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 | Country code for the TikTok Shop data to query. Choose one of the country codes in this field's enum. | — |
keyword | string | No | Keyword for video search | — |
shop_id | string | No | Restrict results to videos promoting the given shop's products. | — |
ads_roas | string | No | Estimated ad ROAS filter. Accepts a single value, a range (`1-2.5`), or open-ended (`<1`, `>5`). | — |
currency | enum (CNY | USD | IDR | VND | THB | MYR | JPY | PHP | GBP | SGD | MXN | EUR | BRL | PLN | CZK | HUF) | Yes | Currency used for revenue-related values and filters. Supported values: 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 videos published by the given creator. | — |
date_range | string | Yes | Date window for this ranking, limited to a maximum of 30 days. Documented choices: `lastDay`, `last7Day`, `last30Day`, a `yyyy-MM-dd~yyyy-MM-dd` range spanning no more than 30 days, or a `yyyy-MM` month. | — |
product_id | string | No | Restrict results to videos mounting the given product. | — |
rank_field | string | No | Legacy shortcut for specifying the ranking field. For ordering, use the `sort_field` object. | — |
sort_field | object | Yes | Sort specification object. Set `field` to a supported field and `type` to `ASC` or `DESC`; documented default is `revenue` descending. | — |
sort_field.type | enum (ASC | DESC) | No | Sort direction: `ASC` for ascending or `DESC` for descending. | — |
sort_field.field | string | No | Name of the ranking field. The provider documents numeric response fields as supported. | — |
is_ai_video | integer | No | Filter by whether the video is AI-generated: 1 for AI-generated videos, 0 for non-AI videos. Omit the field for no filter. | — |
page_number | integer | No | Page number, starting at 1. | 1 |
views_range | string | No | Play count (sum in the selected time range) filter. Same syntax as the website: `<10000`, `10000-100000`, `>1000000`. | — |
category_ids | array | No | Restrict results to videos in the given category IDs. | — |
revenue_range | string | No | Revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms. | — |
followers_range | string | No | Follower count range of the video's creator. | — |
publish_date_range | string | No | Video publish time filter, relative days. Same syntax as the website: `<3` = within 3 days, `<7` = within 7 days, `<30` = within 30 days. | — |
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_shop_video_rank' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"currency": "MYR",
"date_range": "last30Day",
"keyword": "home",
"language": "zh-CN",
"page_size": 10,
"region": "MY",
"sort_field": {
"field": "revenue",
"type": "DESC"
}
}
}'{
"cached": null,
"code": null,
"data": [
{
"ad": 1,
"ad_revenue_ratio": 36.99771277675995,
"ad_view_ratio": 2.596638183917295,
"ads_roas": 2.94,
"ai_video": 0,
"belonged_creator_handle": "ery_muhd"
}
],
"message": null,
"success": true
}This example shows part of the response. Copied content is valid JSON.

