This skill guides you on how to query promotional videos associated with a TikTok Shop product, helping sellers analyze video marketing performance and identify effective influencer content strategies.
Core Concepts
This tool retrieves the list of promotional videos linked to a specific TikTok product. Each video record includes engagement metrics (views, likes, comments, shares, favorites), estimated sales attribution (video sales count and GMV), video metadata (duration, resolution, publish date), and the creator (influencer) ID. This enables sellers to understand which videos drive the most sales for a product and what content patterns work best.
Required input: A productId is mandatory. You can obtain product IDs from the EchoTik product search tool (linkfox-echotik-product-search) or the new product ranking tool (linkfox-echotik-new-product-rank).
Sort fields: Videos can be sorted by views (1), likes (2), shares (3), video sales (4), video GMV (5), or publish date (6).
Pagination: pageSize must be a multiple of 10, max 100. The backend fetches in batches of 10 and merges results.
Parameter Guide
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
| productId | string | Yes | TikTok product ID | - |
| userId | string | No | Filter by influencer ID | - |
| productVideoSortField | integer | No | Sort field: 1=views, 2=likes, 3=shares, 4=video sales, 5=video GMV, 6=publish date | 1 |
| sortType | integer | No | Sort order: 0=ascending, 1=descending | 1 |
| minCreateTime | integer | No | Video publish start time (Unix timestamp in seconds) | - |
| maxCreateTime | integer | No | Video publish end time (Unix timestamp in seconds) | - |
| pageNum | integer | No | Page number | 1 |
| pageSize | integer | No | Results per page (multiple of 10, max 100) | 50 |
How to call
- API endpoint：
POST /echotik/listProductVideo(for full parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/echotik_list_product_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 try different keywords, paginate, or change the zip code in repeated probing; if you need to continue searching, first explain to the user that additional consumption will be incurred.
Output strategy (default script behavior)：
- Alwayswrite the full response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-product-video-<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 an error is reported if the current directory is not writable) - Response body ≤ 8 KB: after saving to disk, print the full JSON to stdout
- Response body > 8 KB: after saving 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 saved 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 putting the entire JSON into the 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 videos by views for a product
{
"productId": "1729382310407603945",
"productVideoSortField": 1,
"sortType": 1,
"pageSize": 20
}
2. Find highest-converting videos (by video sales)
{
"productId": "1729382310407603945",
"productVideoSortField": 4,
"sortType": 1,
"pageSize": 20
}
3. Videos by a specific influencer for a product
{
"productId": "1729382310407603945",
"userId": "7234567890123456789",
"productVideoSortField": 1,
"sortType": 1
}
4. Recent videos in a time range (sorted by GMV)
{
"productId": "1729382310407603945",
"minCreateTime": 1717200000,
"maxCreateTime": 1719792000,
"productVideoSortField": 5,
"sortType": 1
}
5. Videos sorted by publish date (newest first)
{
"productId": "1729382310407603945",
"productVideoSortField": 6,
"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 influencer ID
- 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
- 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) - Hashtag display: Show
hashTagwhen present to help users understand content themes - Playback URL caveat: The
playAddrfield may expire quickly; preferofficialUrlfor sharing
User Expression & Scenario Quick Reference
Applicable Scenarios
| User Says | Scenario |
|---|---|
| "Show me the promotional videos for this TikTok product" | Query videos by product ID |
| "Which videos are driving the most sales for this product" | Sort by video sales (field 4) |
| "What influencer videos are promoting this product" | General video list query |
| "Show me videos by a specific creator for this product" | Filter by userId |
| "Recent promotional videos for this product" | Filter by time range or sort by date |
| "Which TikTok videos have the highest GMV for this product" | Sort by video GMV (field 5) |
| "Analyze the video marketing performance of this product" | Comprehensive video list query |
Not Applicable Scenarios
- Searching for products (use
linkfox-echotik-product-searchinstead) - TikTok new product rankings (use
linkfox-echotik-new-product-rankinstead) - Influencer profile analytics (follower count, bio, overall performance)
- TikTok live-stream data
- Video content creation or editing advice
- TikTok advertising / ad campaign management
- Non-TikTok platform video data
Boundary Judgment
When users ask about "TikTok videos", determine whether they want videos associated with a specific product (this skill) or general TikTok video analytics (not this skill). If they mention a product ID or ask "what videos are promoting product X", this skill applies. If they ask about trending videos in general without a product context, this skill does not apply.
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 expectation of compute consumption is 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.