TikTok Shop Product Rank
Retrieve Kalodata-provided TikTok Shop product rankings for the country selected by `region`; the data is not limited to the US. Filter by product keyword, shop, creator, category, affiliate status, launch timing, or revenue and price ranges. Ranking date windows are limited to 30 days. Set ranking order with the `sort_field` object. Results include product and seller identifiers, sales and revenue metrics, category information, and other returned ranking fields. The tool returns the result in the response to the call.
Pricing
| Condition | Charge |
|---|---|
| Each call | 12 credits/call |
A fixed charge of 12 credits applies to each successful query.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
asc | boolean | No | Legacy ascending-flag field. Use the `sort_field` object to specify the ranking order. | — |
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 | Select the TikTok Shop country/region for the ranking. Choose one of the country codes listed in this parameter's allowed values; the data is not limited to the US. | — |
keyword | string | No | Filter products by a keyword. | — |
shop_id | string | No | Restrict results to the given shop. | — |
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. | — |
need_all | boolean | No | If true, include products that have no sales in the selected period. Default false (sales-only). | — |
video_id | string | No | Return the products mounted on the given video. | — |
page_size | integer | No | Page size. Maximum 100 records per query. Default 10. | 10 |
creator_id | string | No | Filter for products promoted by this creator. When combined with `shop_id`, returns the creator's products for that shop. | — |
date_range | string | Yes | Ranking time window; no more than 30 days. Accepts `lastDay`, `last7Day`, or `last30Day`, a `yyyy-MM-dd~yyyy-MM-dd` range spanning no more than 30 days, or `yyyy-MM` (subject to the 30-day limit). | — |
need_extra | boolean | No | Whether to include extra product information such as seller name and SKU quantity. | — |
need_image | integer | No | Whether main image URL is needed: 0-not needed (default), 1-return official URL, 2-return kalo_data image URL (paid service required) | — |
rank_field | string | No | Legacy ranking-field field. Use the `sort_field` object to specify the ranking field and direction. | — |
sort_field | object | Yes | Ranking order, specified as an object with `field` and `type`. Use this field for ranking configuration. | — |
sort_field.type | enum (ASC | DESC) | No | Ranking direction: `ASC` for ascending or `DESC` for descending. | — |
sort_field.field | string | No | Name of the response's numeric field to rank by, such as `revenue`, `sales_volumn`, or `revenue_growth_rate`. | — |
launch_date | enum (<3 | <7 | >30) | No | Days since product launch. <3 = within 3 days, <7 = within 7 days, >30 = older than 30 days. | — |
page_number | integer | No | Page number, starting at 1. | 1 |
category_ids | array | No | Filter the ranked products by category ID. | — |
is_affiliate | enum (0 | 1) | No | Affiliate-program filter. 0 = non-affiliate only, 1 = affiliate only. | — |
delivery_type | enum (local | global) | No | Delivery mode filter. `local` = domestic fulfillment, `global` = cross-border. | — |
livestream_id | string | No | Return the products mounted in the given live stream. | — |
revenue_range | string | No | Revenue range filter, in the same currency as the request `currency`. Also supports `<10` / `>1` forms. | — |
is_tts_product | enum (0 | 1) | No | TTS (Tiktok fully-managed) product filter. 1 = fully managed only, 0 = self-fulfilled only. | — |
commission_rate | string | No | Commission rate filter for affiliate products. Accepts range (`15-35`), open-ended (`<10`, `>=30`), or a single ratio. | — |
unit_price_range | string | No | Product unit-price range filter. | — |
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_product_rank' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"currency": "GBP",
"date_range": "last30Day",
"delivery_type": "global",
"keyword": "phone case",
"language": "en-US",
"page_size": 20,
"region": "GB",
"sort_field": {
"field": "revenue",
"type": "DESC"
}
}
}'{
"cached": null,
"code": null,
"data": [
{
"commission_rate": 8.0,
"launch_date": "2026-09-12",
"live_revenue": 0.0,
"master_image_url": null,
"pri_category": {
"category_id": "601739",
"category_name": "Phones & Electronics"
},
"product_id": "1729914352412694833"
}
],
"message": null,
"success": true
}This example shows part of the response. Copied content is valid JSON.

