SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-kalodata-tiktok-video

linkfox-kalodata-tiktok-video

Design & creation

View repository

Updated 10-16 00:00

About this skill

Kalodata - TikTok Video Search & Detail

This skill supports a two-step TikTok video workflow via the Kalodata data source:

  1. Browse TikTok Shop video leaderboards to discover high-performing shoppable videos.
  2. Fetch one video's full performance detail by videoId.

Use the search endpoint when the user wants rankings, hot videos, viral videos, or video discovery. Use the detail endpoint when the user already has a videoId or has selected one video from a ranking result.

Core Concepts

The video ranking endpoint returns a paginated leaderboard filtered by region, dateRange, language, currency, and optional GMV range revenue_range. Use sortField to sort by revenue. Each video row includes identity, engagement, revenue, ad-performance, and creator fields. Results are paginated with pageNumber (1-5) and pageSize (5-100).

The video detail endpoint fetches one shoppable TikTok video by videoId. It returns the video's engagement metrics, monetization metrics, advertising metrics, creator identity, region, duration, and linked product count. The videoId usually comes from the ranking response field video_id.

Both endpoints may reflect a statistical delay (T+1). See references/api.md for full request and response details.

Data Fields

Ranking rows include:

Field Description
video_id Video unique ID; pass this as videoId for detail lookup
video_title Video title / caption
views Video view count
digg_count / comment_count / share_count Likes, comments, and shares
revenue Total GMV in the requested currency
revenue_growth_rate Revenue growth rate (%)
ad / ad_view_ratio / ad_revenue_ratio / ads_roas Ad and advertising performance fields
belonged_creator_id / belonged_creator_handle Creator identity
creator_debut Creator debut date

Detail rows additionally include:

Field Description
video_region Video region; may be empty
sales_volumn Sales volume; field is spelled volumn
video_gpm GMV per mille (revenue per 1000 views)
ads_views / ad_cpa / ads_period Ad views, CPA, and ad running period
duration Video duration in seconds
product_number Number of products linked in the video

Parameter Guide

Video ranking (/kalodata/video/rank)

Parameter Type Required Description
region string No Market region code, e.g. US
dateRange string No Time window, e.g. last7Day, last30Day
pageNumber integer No Page number, 1-5
pageSize integer No Page size, 5-100
language string No Response language, e.g. zh-CN, en-US
currency string No Currency for monetary metrics, e.g. USD
category_id string No Category ID filter
shop_id string No Shop ID filter
creator_id string No Creator ID filter
product_id string No Product ID filter
revenue_range string No GMV range because response field revenue is total GMV; examples: 1-100, >1000, <100
followers_range string No Creator follower range filter
ads_roas number No Advertising ROAS filter
sortField object No GMV sorting specification, e.g. {"field":"revenue","type":"DESC"}

Video detail (/kalodata/video/detail)

Parameter Type Required Description
videoId string Yes TikTok video ID from ranking field video_id or a TikTok video URL
region string No Market region code, e.g. US
dateRange string No Time window, e.g. last7Day, last30Day
language string No Response language, e.g. zh-CN, en-US
currency string No Currency for monetary metrics, e.g. USD

How to call

  • API endpoint：POST /kalodata/video/rank or POST /kalodata/video/detail(for full parameters/responses/error codes see references/api.md）
  • Python script：python scripts/kalodata_video_search.py '<JSON 参数>' [--inline] or python scripts/kalodata_video_detail.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 the zip code to probe continuously; if you need to continue searching, 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-kalodata-tiktok-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 variable SESSION_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 --inline to force full printing to stdout (also written to disk)

Data reading suggestions: first look at the summary to judge whether it is sufficient; when specific fields are needed, prefer using jq or ConvertFrom-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, and LINKFOXAGENT_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. Browse top TikTok videos in the US

{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}

2. Filter by GMV and rank by GMV

{"region":"US","dateRange":"last7Day","revenue_range":"1-100","sortField":{"field":"revenue","type":"DESC"},"pageSize":10,"pageNumber":1,"currency":"USD"}

3. Fetch one video's detail

{"videoId":"7659161409279806734","region":"US","dateRange":"last7Day","currency":"USD"}

4. Discovery-to-detail workflow

Run kalodata_video_search.py first, choose a row's video_id, then pass that value as videoId to kalodata_video_detail.py.

Display Rules

  1. Present ranking results in a table with title, video ID, views, engagement, revenue, ad indicators, and creator handle.
  2. Present detail results as one grouped profile: identity, engagement, monetization, ads, creator, duration, and linked products.
  3. Always label dateRange, region, and currency when showing metrics.
  4. Use the exact field name sales_volumn.
  5. video_gpm is GMV per mille; do not display it as a percentage.
  6. Preserve ranking order unless the user explicitly requests a supported sortField.

Important Limitations

  • Ranking is not keyword search; it browses leaderboards by region and time window.
  • The backend supports GMV range filtering through revenue_range; revenue in the response is GMV, not profit or ad spend.
  • Detail requires videoId; it cannot find a video by title alone.
  • The ranking response does not include total/page count; result count is data.length.
  • pageNumber is limited to 1-5 and pageSize is limited to 5-100.
  • Transient upstream errors may appear as errcode 501 with a Kalodata HTTP 554 message. Retry the same parameters once or twice; do not change parameters automatically.
  • Use the matching Kalodata product/creator/shop/livestream skills for non-video entities.

User Expression & Scenario Quick Reference

Applicable -- TikTok video ranking or video detail lookup:

User Says Scenario
"TikTok video rankings", "TikTok video ranking" Video ranking lookup
"TikTok popular videos", "TikTok viral videos" Top or viral video ranking
"TikTok sales video ranking", "top TikTok videos" Region-specific shoppable video leaderboard
"TikTok video details", "TikTok sales video data" Single video detail lookup
"video views", "video engagement data", "video GPM" Video engagement or monetization metrics
"kalodata video search/detail" Direct data source reference

Not applicable -- Needs beyond TikTok videos:

  • TikTok product / creator / shop / livestream rankings or details
  • Keyword-based video or product search
  • TikTok advertising / ad campaign management
  • Video editing, video download, or content creation

Compute consumption rules

Each call consumes 7.0 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:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. 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.