TikTok Shop Creator Rank
12 credits/call
ae_tiktok_shop_creator_rank
Retrieve Kalodata-provided TikTok Shop creator rankings by performance, with filters for country, category, shop, product, creator type, keyword, revenue, followers, and engagement. Choose a country with `region`; supported countries are the codes listed in the parameter schema, so this is not limited to the US. Ranking date windows are limited to 30 days. Use the `sort_field` object to choose the sort field and direction, and paginate with `page_number` and `page_size`. Results include creator ranking metrics and may include category information.
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 sorting shortcut. For sorting, use the `sort_field` object instead. | — |
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 | TikTok Shop country whose creator ranking data to query. Select one of the country codes listed in this parameter's allowed values; coverage is not limited to the US. | — |
keyword | string | No | Keyword for creator search | — |
shop_id | string | No | Restrict to creators collaborating with the given shop (any video / live / showcase mounting the shop's products with exposure). | — |
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 |
date_range | string | Yes | Date window for the ranking query. The ranking period is limited to a maximum of 30 days; choose a supported range that stays within this limit. | — |
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) | — |
product_id | string | No | Restrict to creators who have promoted the given product. | — |
rank_field | string | No | Legacy sort-field shortcut. Use the `sort_field` object to specify sorting instead. | — |
sort_field | object | Yes | Sort spec. `field` accepts any numeric field from the response; `type` is ASC or DESC. Defaults to `{"field":"revenue","type":"DESC"}`. | — |
sort_field.type | enum (ASC | DESC) | No | Sort direction. | — |
sort_field.field | string | No | Sort field name. Any numeric field returned by the endpoint is supported (e.g. revenue, sales_volumn, revenue_growth_rate). | — |
page_number | integer | No | Page number, starting at 1. | 1 |
category_ids | array | No | Deprecated, use `category_id_list`. List of category IDs to restrict creator revenue. | — |
creator_type | enum (BELONGED_TO_SELLER | INDEPENDENT) | No | Creator type filter. BELONGED_TO_SELLER = seller's own creator, INDEPENDENT = independent affiliate creator. | — |
need_category | integer | No | Whether category information is needed (0 = not needed, 1 = needed) | — |
revenue_range | string | No | Revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms. | — |
engagement_rate | enum (LOW | MEDIUM | HIGH) | No | Engagement rate bucket. LOW = <8%, MEDIUM = 8%-20%, HIGH = >20%. | — |
followers_range | string | No | Follower count range filter. Also supports `<100` / `>1000` forms. | — |
category_id_list | string | No | Comma-separated category IDs (preferred over `category_ids`). | — |
need_ter_category | integer | No | Whether ter category information is needed (0 = not needed, 1 = needed) | — |
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_creator_rank' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"creator_type": "INDEPENDENT",
"currency": "USD",
"date_range": "last30Day",
"keyword": "magnesium",
"language": "en-US",
"need_category": 1,
"need_ter_category": 1,
"page_number": 1,
"page_size": 100,
"region": "US",
"sort_field": {
"field": "revenue",
"type": "DESC"
}
}
}'Response exampleresponse.json
{
"cached": null,
"code": null,
"data": [
{
"category_id_list": [
"700645"
],
"category_list": [
"Health"
],
"content_views": "171",
"creator_followers": "208",
"creator_handle": "@7in1magnesium",
"creator_id": "7351662022923830318"
}
],
"message": null,
"success": true
}This example shows part of the response. Copied content is valid JSON.

