TikTok Shop Video Rank

12 credits/call
ae_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.

VideoSocial
12 credits/call

Pricing

12 credits/call
ConditionCharge
Each call12 credits/call

Fixed charge: 12 credits per call.

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
ascbooleanNoLegacy ascending flag. For ordering, use the `sort_field` object.—
regionenum (US | BR | MX | ID | JP | MY | PH | SG | TH | VN | GB | ES | DE | FR | IT | PL | NL | BE | CZ | AT | GR | PT | HU | IE)YesCountry code for the TikTok Shop data to query. Choose one of the country codes in this field's enum.—
keywordstringNoKeyword for video search—
shop_idstringNoRestrict results to videos promoting the given shop's products.—
ads_roasstringNoEstimated ad ROAS filter. Accepts a single value, a range (`1-2.5`), or open-ended (`<1`, `>5`).—
currencyenum (CNY | USD | IDR | VND | THB | MYR | JPY | PHP | GBP | SGD | MXN | EUR | BRL | PLN | CZK | HUF)YesCurrency 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.—
languageenum (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)YesLanguage 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_sizeintegerNoPage size. Maximum 100 records per query. Default 10.10
creator_idstringNoRestrict results to videos published by the given creator.—
date_rangestringYesDate 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_idstringNoRestrict results to videos mounting the given product.—
rank_fieldstringNoLegacy shortcut for specifying the ranking field. For ordering, use the `sort_field` object.—
sort_fieldobjectYesSort specification object. Set `field` to a supported field and `type` to `ASC` or `DESC`; documented default is `revenue` descending.—
sort_field.typeenum (ASC | DESC)NoSort direction: `ASC` for ascending or `DESC` for descending.—
sort_field.fieldstringNoName of the ranking field. The provider documents numeric response fields as supported.—
is_ai_videointegerNoFilter by whether the video is AI-generated: 1 for AI-generated videos, 0 for non-AI videos. Omit the field for no filter.—
page_numberintegerNoPage number, starting at 1. 1
views_rangestringNoPlay count (sum in the selected time range) filter. Same syntax as the website: `<10000`, `10000-100000`, `>1000000`.—
category_idsarrayNoRestrict results to videos in the given category IDs.—
revenue_rangestringNoRevenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms.—
followers_rangestringNoFollower count range of the video's creator.—
publish_date_rangestringNoVideo 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.

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_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"
    }
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "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.