This skill queries TikTok Shop video ranking data via the EchoTik data source, helping cross-border sellers and marketers discover top-performing videos in daily, weekly, or monthly rankings. Unlike linkfox-echotik-list-video (which lists videos by region with free filters), this tool returns a dated ranking of videos sorted by a chosen metric.
Core Concepts
EchoTik is a TikTok Shop analytics platform. This tool returns ranked video lists for a selected day, week, or month, ordered by a selected ranking metric.
Required input: date, rankType, region, and videoRankField are all mandatory. There are no defaults for required fields.
Related skill: To list videos by region with free filters (creator / product / views range / ad / AI flags) instead of a dated ranking, use linkfox-echotik-list-video. This skill is for ranked, date-scoped video charts.
Data Fields
The response data[*] video object has 25 documented fields. Metric names begin with total but represent the ranking period's cumulative value. Key fields:
| Field | Description |
|---|---|
| videoId / officialUrl / coverUrl | Video ID / TikTok URL / cover image URL |
| videoDesc / duration / createDate | Description / duration (seconds) / publish date |
| userId / uniqueId / nickName / avatar | Creator ID / TikTok account ID / nickname / avatar |
| category / region | Creator category / marketplace code |
| totalViewsCnt / totalDiggCnt / totalCommentsCnt | Period views / likes / comments |
| totalSharesCnt / totalFavoritesCnt | Period shares / favorites |
| totalVideoSaleCnt / totalVideoSaleGmvAmt | Period video sales (units, estimated) / sales GMV (estimated) |
| salesFlagText / createdByAiText | Selling video flag / AI video flag (yes/no) |
| productCategoryList / videoProducts | Selling product categories / products |
| sourceType / sourceTool | Product source / source tool |
Full field list with types is in
references/api.md. This shape differs fromlinkfox-echotik-list-video(no width/height/ratio, no 1d/7d/30d breakdowns, noisAdText).
Parameter Guide
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| date | string | Yes | - | Query date, YYYY-MM-DD |
| rankType | integer | Yes | - | Ranking type (see values below) |
| region | string | Yes | - | Marketplace code. See supported list below |
| videoRankField | integer | Yes | - | Ranking metric (see values below) |
| productCategoryId | string | No | - | Level-1 product category ID for filtering sales-video rankings |
| createdByAi | string | No | - | AI-video filter: true or false |
| pageNum | integer | No | 1 | Page number, starts at 1 |
| pageSize | integer | No | 50 | Page size — must be a multiple of 10, max 100 |
rankType values
| Value | Meaning |
|---|---|
| 1 | Daily ranking (day) |
| 2 | Weekly ranking (week) |
| 3 | Monthly ranking (month) |
videoRankField values
| Value | Meaning | Verified |
|---|---|---|
| 1 | Rank by views (播放量) | ✓ 200 |
| 2 | Rank by video sales (视频销量) | ✓ 200 |
Metric sparsity: when ranking by a given
videoRankField, the other metric fields may return 0 (ranking by sales → views/likes/comments can be 0; ranking by views → sales/GMV can be 0).
Supported Marketplaces
US (United States), ID (Indonesia), TH (Thailand), PH (Philippines), MY (Malaysia), VN (Vietnam), GB (United Kingdom), MX (Mexico), SG (Singapore), SA (Saudi Arabia), BR (Brazil), ES (Spain), JP (Japan), DE (Germany), IT (Italy), FR (France)
When the user doesn't specify a marketplace, ask or default to US.
How to call
- API endpoint：
POST /echotik/listVideoRank(for full parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/echotik_list_video_rank.py '<JSON 参数>' [--inline] - Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is called only once, and the script includes a 24h local cache. On failure/empty results, do not automatically switch keywords, paginate, or change the postal code for continuous trial and error; if continued retrieval is needed, first explain to the user that additional consumption will be incurred.
Output strategy (script default behavior)：
- Alwayswrite the full response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-list-video-rank-<timestamp>.json（<cwd>is the working directory when the script runs, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error) - Response body ≤ 8 KB: after writing to disk, print the full JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, the length of the largest list field + the first 3 samples) - Add
--inlineto force full printing to stdout (also written to disk)
Data reading suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract as needed from the saved json file, avoiding bringing the entire JSON into context.
Resolve authentication and compute issues
When the following abnormal situations occur, use references/onboarding.md to guide resolution:
Abnormal situations
- API Key not configured: the environment variable is not configured
LINKFOX_AGENT_API_KEY, andLINKFOXAGENT_API_KEY。 - response 401 or 402 status code
- Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.
Usage Examples
1. Top US videos by views on a given day
{
"date": "2026-08-10",
"rankType": 1,
"region": "US",
"videoRankField": 1,
"pageNum": 1,
"pageSize": 20
}
2. Weekly UK video ranking
{
"date": "2026-08-10",
"rankType": 2,
"region": "GB",
"videoRankField": 1
}
3. Monthly US sales ranking filtered to AI videos
{
"date": "2026-08-01",
"rankType": 3,
"region": "US",
"videoRankField": 2,
"createdByAi": "true",
"productCategoryId": "601450",
"pageNum": 1,
"pageSize": 20
}
Display Rules
- Present data in tables: Show video description (truncated if long), views, likes, comments, shares, video sales, video GMV, publish date, and creator ID.
- Rank order: Results are already ranked by the chosen
videoRankField; preserve and surface the ranking order. - Link to original: When
officialUrlis available, provide it so users can view the video on TikTok. - Estimation notice: Video sales and GMV are estimated values; remind users these are approximations.
- Result count: Always inform the user of
totalrecords and the current page; suggest pagination when the result set is large.
Important Limitations
- All four required fields:
date,rankType,region,videoRankFieldare mandatory; no defaults are applied. - Ranking data lags 1–2 days: Recent ranking data may be unavailable and return
errcode:10000("no matching data"). Use an earlier date if needed. - Ranking vs. listing: This is a dated ranking. For region-scoped video listing with free filters (creator / views range / ad / AI flags), use
linkfox-echotik-list-video. - No secondary processing: Results are live queries; secondary SQL/data processing is not available.
User Expression & Scenario Quick Reference
Applicable — TikTok video ranking / charts:
| User Says | Scenario |
|---|---|
| "TikTok video ranking" / "TikTok top video chart" | Video ranking by selected period and metric |
| "the hottest TikTok videos this week" | Weekly ranking (rankType:2) |
| "this month's TikTok commerce video chart" | Monthly sales ranking (rankType:3) |
| "TikTok commerce video ranking" | Ranked selling videos (inspect sales/GMV columns) |
| "UK TikTok video chart" | region=GB ranking |
Not applicable — Needs beyond dated video ranking:
- Region-scoped video listing with free filters (use
linkfox-echotik-list-video) - Videos for one specific product by
productId(uselinkfox-echotik-product-video) - Video download URL resolution (use
linkfox-echotik-get-video-download-url) - TikTok product / seller rankings
Boundary judgment: When users say "video ranking/video chart/hottest videos" with a date or region context, this skill applies. If they want to filter videos by creator, views range, or ad/AI flags without a ranking, use linkfox-echotik-list-video.
Compute consumption rules
Consumes 5 compute.
Users pay fees due to compute consumption. Please fully assess: when this skill needs to be called frequently, or when the user's expectations for compute consumption are insufficient, be sure to remind the user and let the user decide whether to continue.
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
- The functionality or purpose described in this skill does not match actual behavior
- The skill's results do not match the user's intent
- The user expresses dissatisfaction or praise about this skill
- Anything you believe could be improved
Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.