This skill searches and analyzes TikTok video data, helping cross-border sellers and marketers discover top-performing videos, benchmark content strategies, and evaluate video-level engagement and sales attribution across TikTok marketplaces.
Core Concepts
EchoTik is a TikTok Shop analytics platform. This tool lists TikTok videos with rich filtering — by region, creator, product, category, views, duration, publish time, and ad/AI/selling flags — and returns engagement metrics (views, likes, comments, shares, favorites), estimated sales attribution (video sales count and GMV), and video metadata (duration, resolution, cover, publish date).
Required input: region is mandatory. Optional filters narrow by creator (userId), product (productId), category (productCategoryId), views range, duration range, publish-time range, and video type (ad / AI / selling).
Sort fields: videos can be sorted by likes (1), publish time (2), or views (3, default).
Pagination: pageSize must be a multiple of 10, max 100. The backend fetches in batches of 10 and merges results.
Related skill: This tool lists videos by region/filters (no product required). To get videos associated with one specific product, use linkfox-echotik-product-video with a productId instead.
Data Fields
| Field | Description |
|---|---|
| videoId | Video ID |
| videoDesc | Video description / caption |
| officialUrl | TikTok official video URL |
| coverUrl | Video cover image URL |
| duration | Video duration (seconds) |
| width / height | Video dimensions in pixels (e.g. 576×1090) |
| ratio | Video resolution label (e.g. 540p/720p) |
| dataSize | Video file size |
| createDate | Publish date |
| userId / uniqueId / avatar | Creator ID / TikTok unique_id / creator avatar |
| totalViewsCnt | Total views (1d/7d/30d breakdown: totalViews1dCnt / 7dCnt / 30dCnt) |
| totalDiggCnt | Total likes (1d/7d/30d breakdown: totalDigg1dCnt / 7dCnt / 30dCnt) |
| totalCommentsCnt | Total comments |
| totalSharesCnt | Total shares |
| totalFavoritesCnt | Total favorites |
| totalVideoSaleCnt | Video sales (units) |
| totalVideoSaleGmvAmt | Video sales GMV (amount) |
| salesFlagText | Selling-video flag (Yes/No) |
| isAdText | Ad-video flag (Yes/No) |
| createdByAiText | AI-video flag (Yes/No/Unknown) |
| productCategoryList | Product categories |
| videoProducts | Related products |
| region | Marketplace code |
| sourceType / sourceTool | Source type / source tool |
Parameter Guide
Required & Region
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| region | string | Yes | - | Marketplace code. See supported list below |
Creator / Product / Category
| Parameter | Type | Description |
|---|---|---|
| userId | string | Filter by creator (influencer) ID |
| productId | string | Filter by related product ID |
| productCategoryId | string | Filter by related product category ID |
Engagement / Duration / Time
| Parameter | Type | Description |
|---|---|---|
| minTotalViewsCnt / maxTotalViewsCnt | integer | Total-views range (min / max) |
| minDuration / maxDuration | integer | Duration range in seconds (min / max) |
| minCreateTime / maxCreateTime | integer | Publish-time range, Unix timestamp in seconds (min / max) |
Video Type Flags
| Parameter | Type | Description |
|---|---|---|
| salesFlag | integer | Selling video: 0=non-selling, 1=selling (with cart) |
| isAd | integer | Ad video: 0=non-ad, 1=ad (paid traffic) |
| createdByAi | string | AI video: "true"=AI, "false"=non-AI (string, not boolean) |
Sorting & Pagination
| Parameter | Type | Default | Description |
|---|---|---|---|
| videoSortField | integer | 3 | Sort field: 1=likes (total_digg_cnt), 2=publish time (create_time), 3=views (total_views_cnt) |
| sortType | integer | 1 | Sort order: 0=ascending, 1=descending |
| pageNum | integer | 1 | Page number (starts at 1) |
| pageSize | integer | 50 | Page size — must be a multiple of 10, max 100 |
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/listVideo(For full parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/echotik_list_video.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 has a 24h local cache. On failure/empty results, do not automatically switch keywords, paginate, or change zip codes to probe continuously; if you need to continue searching, first explain to the user that extra 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-<timestamp>.json（<cwd>is the working directory when the script runs; in Claude Code this is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user task;writing to /tmp is prohibited, 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 to use jqorConvertFrom-Json to extract on demand 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
- The 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
{
"region": "US",
"videoSortField": 3,
"sortType": 1,
"pageSize": 20,
"pageNum": 1
}
2. Highest-converting selling videos (by video sales)
{
"region": "US",
"salesFlag": 1,
"videoSortField": 3,
"sortType": 1,
"pageSize": 20
}
3. Videos by a specific creator
{
"region": "US",
"userId": "7234567890123456789",
"videoSortField": 1,
"sortType": 1
}
4. High-view videos in a time range (sorted by likes)
{
"region": "GB",
"minTotalViewsCnt": 100000,
"minCreateTime": 1717200000,
"maxCreateTime": 1719792000,
"videoSortField": 1,
"sortType": 1
}
5. Recent AI videos sorted by publish date
{
"region": "US",
"createdByAi": "true",
"videoSortField": 2,
"sortType": 1,
"pageSize": 50
}
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
- Link to original: When
officialUrlis available, provide it so users can view the video on TikTok - Cover image: If
coverUrlis present, mention it so the user knows video thumbnails are available - Duration formatting: Convert
duration(seconds) to a readable format (e.g., "1:30" for 90 seconds) - Estimation notice: Video sales and GMV are estimated values, remind users these are approximations
- Multi-period metrics: When relevant, mention 1d/7d/30d views/likes breakdowns are available in the saved JSON
- Result count: Always inform the user of
totalrecords and the current page; suggest pagination or tighter filters when the result set is large
Important Limitations
- Region required:
regionis mandatory; no default is applied by the API. - pageSize rule: Must be a multiple of 10 (max 100). Other values may be rejected or adjusted.
- createdByAi is a string: Pass
"true"/"false"(not boolean) — the value is validated against^(true|false)$. - Timestamps:
minCreateTime/maxCreateTimeare Unix timestamps in seconds. - Category/product IDs:
productId/productCategoryId/userIdare internal IDs — obtain them from prior results. - No secondary processing: Results are live queries, not stored in a database; secondary SQL/data processing is not available.
- Product-specific videos: To list videos for one specific product (by
productId), preferlinkfox-echotik-product-video; hereproductIdis only a filter within a region-scoped video listing.
User Expression & Scenario Quick Reference
Applicable — TikTok video discovery and performance analysis:
| User Says | Scenario |
|---|---|
| "TikTok trending videos" / "TikTok top videos" | List videos sorted by views (field 3) |
| "TikTok selling video ranking" | Filter salesFlag=1, sort by views/sales |
| "A certain creator's TikTok videos" | Filter by userId |
| "TikTok paid-traffic videos" / "TikTok ad videos" | Filter isAd=1 |
| "TikTok AI videos" | Filter createdByAi="true" |
| "Recent high-play TikTok videos" | Views range + time range |
| "Which TikTok video has the highest GMV" | Sort by views, inspect GMV column |
Not applicable — Needs beyond region-scoped video listing:
- Videos for one specific product by
productId(uselinkfox-echotik-product-video) - TikTok product search or rankings (use EchoTik product search/rank skills)
- TikTok creator/influencer profile analytics (followers, bio)
- TikTok live-stream data
- Video download URL resolution (use
linkfox-echotik-get-video-download-url) - Non-TikTok platform video data
Boundary judgment: When users ask about "TikTok videos", determine whether they want a region-scoped video listing with filters (this skill) or videos tied to one known product (linkfox-echotik-product-video). If they mention a region or filters like "trending/selling/paid-traffic videos" without a specific product, this skill applies.
Compute consumption rules
Consumes 5 compute.
Users will be charged for computing power consumption. Please fully assess: when this skill needs to be called frequently, or when the user has insufficient expectations for the amount of computing power consumption, 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.