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

linkfox-kalodata-tiktok-livestream

Data & analytics

View repository

Updated 10-16 00:00

About this skill

Kalodata - TikTok Livestream Search & Detail

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

  1. Browse TikTok Shop livestream leaderboards to discover top-performing shoppable livestreams (带货直播).
  2. Fetch one livestream's full performance detail by livestreamId.

Use the search (rank) endpoint when the user wants rankings, hot livestreams, or livestream discovery. Use the detail endpoint when the user already has a livestreamId or has selected one livestream from a ranking result.

Core Concepts

The livestream ranking endpoint returns a paginated leaderboard filtered by region, dateRange, language, currency, and optional sortField. The default ranking order is by revenue (GMV) descending. Each livestream row includes identity, timing, scale, and creator fields. Results are paginated with pageNumber (1-5) and pageSize (5-100). The response does not include a total count — paginate until a page returns fewer than pageSize items. Money fields (revenue, unit_price) are returned as strings on the ranking endpoint.

The livestream detail endpoint fetches one shoppable TikTok livestream by livestreamId. It returns a 1-element array with the single livestream's full detail (12 fields), including viewers, numeric revenue, gpm, and product_number. There is no pagination and no total. The livestreamId usually comes from the ranking response field livestream_id.

Field names/types differ between the two endpoints: DETAIL uses viewers (RANK uses views); DETAIL revenue is a number (RANK revenue is a string); DETAIL has gpm and lacks unit_price (RANK has unit_price and lacks gpm). Do not assume field names/types carry over between the two endpoints.

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

Data Fields

Ranking rows (each item in data from /kalodata/livestream/rank):

Field Type Description
livestream_id string Livestream unique ID; pass this as livestreamId for detail lookup
livestream_title string Livestream title
creator_id string Creator unique ID (string to preserve precision)
creator_handle string Creator handle / username
livestream_start_time integer Start time, epoch milliseconds
livestream_end_time integer End time, epoch milliseconds
livestream_duration integer Duration in seconds
revenue string Total revenue / GMV in the requested currency — returned as a string, e.g. "185590.52"
unit_price string Average unit price in the requested currency — returned as a string, e.g. "265.89"
views integer Total views (note: RANK uses views)
record_type string Record type (e.g. SHORT)

Detail rows (the single item in data from /kalodata/livestream/detail):

Field Type Description
livestream_id string Livestream unique ID (matches the requested livestreamId)
livestream_title string Livestream title (e.g. 24 HOUR STREAM)
creator_id string Creator unique ID (string to preserve precision)
creator_handle string Creator handle / username (e.g. pokepiglt)
livestream_start_time integer Start time, epoch milliseconds
livestream_end_time integer End time, epoch milliseconds
livestream_duration integer Duration in seconds
record_type string Record type (e.g. SHORT)
viewers integer Total viewers (note: DETAIL uses viewers, NOT views)
revenue number Livestream revenue / GMV as a number in the requested currency (e.g. 185590.52) — a number here, a string on the RANK endpoint
gpm number GMV per mille (revenue per 1,000 impressions) — DETAIL-only, absent from RANK
product_number integer Number of products sold/promoted during the livestream

Money fields are strings on RANK, numbers on DETAIL. Parse RANK revenue/unit_price (float(), Number(), or ConvertFrom-Json) before numeric comparison or formatting. Use the exact field name for the endpoint you are reading (views on RANK, viewers on DETAIL).

Parameter Guide

Livestream ranking (/kalodata/livestream/rank) — all parameters optional:

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
followers_range string No Creator follower range filter
sortField object No Sorting specification; pass {} for the default ranking order

Livestream detail (/kalodata/livestream/detail):

Parameter Type Required Description
livestreamId string Yes Target livestream's unique ID (camelCase), e.g. 7661409374878878494. Typically obtained from the ranking field livestream_id
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/livestream/rank(leaderboard) or POST /kalodata/livestream/detail(details) (for full parameters/responses/error codes see references/api.md）
  • Python script：python scripts/kalodata_livestream_search.py '<JSON 参数>' [--inline](leaderboard) or python scripts/kalodata_livestream_detail.py '<JSON 参数>' [--inline](details)
  • 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 it will incur additional consumption.

Output strategy (script default behavior)：

  • Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-livestream-<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 task;writing to /tmp is prohibited, if the current directory is not writable, report an error)
  • 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, length of the largest list field + first 3 samples)
  • Add --inline to force full printing to stdout (also saved 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 putting 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: environment variable not configured LINKFOX_AGENT_API_KEY, and also not configured LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值", or content with a similar meaning.

Usage Examples

1. Browse top TikTok livestreams in the US

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

2. Fetch one livestream's detail

{"livestreamId":"7661409374878878494","region":"US","dateRange":"last7Day"}

3. Discovery-to-detail workflow

Run kalodata_livestream_search.py first, choose a row's livestream_id, then pass that value as livestreamId to kalodata_livestream_detail.py.

Display Rules

  1. Present data only: Show the ranking in a clear table (livestream title, creator handle, revenue, views, duration, unit price, start/end times) and the detail as one grouped profile, without subjective business advice.
  2. Ranking order: The default order is revenue (GMV) descending; there is no explicit rank field — position is implied by order. Preserve it unless the user explicitly requests a supported sortField.
  3. Currency awareness: Display the requested currency alongside revenue/unit_price (rank) or revenue/gpm (detail).
  4. Money as strings on RANK: RANK revenue and unit_price are returned as strings (e.g. "185590.52") — parse them before numeric comparison or formatting. DETAIL revenue is a number. Use the exact field name when extracting with jq / ConvertFrom-Json.
  5. Viewers vs views: Use views for ranking rows and viewers for detail rows — do not mix them.
  6. GPM: gpm is GMV per mille (detail-only) — present with appropriate precision (e.g. 903.79), not as a percentage.
  7. Time fields: livestream_start_time/livestream_end_time are epoch milliseconds; livestream_duration is seconds. Format human-readable local times when displaying.
  8. Time window: Always label which dateRange the data covers (e.g. "last 7 days").
  9. Pagination hint: The ranking response has no total/page count; if a full page is returned, suggest the user can request the next page (up to pageNumber 5).
  10. Single entity: The detail is one livestream — do not present it as a ranking or leaderboard.

Important Limitations

  • Ranking is not keyword search: It browses a livestream leaderboard filtered by region/time; it does not search livestreams by keyword.
  • Detail requires livestreamId: It cannot find a livestream by title alone. Obtain livestreamId from the ranking field livestream_id.
  • Max 5 pages, page size 5-100: pageNumber is limited to 1-5; out of range returns errcode 501, errmsg "page_number 范围为 1-5，当前: <n>". pageSize must be between 5 and 100.
  • No total/page count: Neither response includes total or page-count fields; paginate the ranking until a page returns fewer than pageSize items.
  • Field names/types differ between endpoints: DETAIL uses viewers (RANK uses views); DETAIL revenue is a number (RANK revenue is a string); DETAIL has gpm and lacks unit_price (RANK has unit_price and lacks gpm). Do not assume field names/types carry over.
  • Data delay: Both endpoints may have a statistical delay (T+1).
  • Transient upstream errors: The gateway may occasionally return errcode 501, errmsg "调用 Kalodata 接口失败: Kalodata API HTTP 554: " (a transient upstream Kalodata error). Retry the same parameters once or twice; do not change parameters.
  • Unsupported sort/filter: If a requested sortField is not accepted by the gateway, do NOT attempt workarounds — inform the user and fall back to the default ranking order.
  • Use the matching Kalodata skills for non-livestream entities: creator/product/video/shop rankings or details.

User Expression & Scenario Quick Reference

Applicable -- TikTok livestream ranking or livestream detail lookup:

User Says Scenario
"TikTok直播排行榜", "TikTok直播排行" Livestream ranking lookup
"TikTok热销直播", "top TikTok livestreams" Livestream leaderboard by region
"近7天TikTok直播榜", "美国TikTok直播排名" Time-windowed / region-filtered ranking
"Kalodata直播榜" Direct data source reference
"TikTok直播详情", "TikTok直播数据" Single livestream detail lookup
"这场直播的观看人数", "这场直播卖了多少钱" Viewers / revenue / GPM for a specific livestream
"TikTok livestream detail", "kalodata livestream search/detail" Direct detail/rank fetch

Not applicable -- Needs beyond TikTok livestreams:

  • TikTok creator/product/video/shop rankings or details (use the corresponding Kalodata skills)
  • A livestream's detail without a known livestreamId (first obtain the ID via the ranking endpoint)
  • Amazon / Shopify / 1688 / other platforms' livestream data
  • TikTok ad campaign management or content creation

Boundary judgment: When users say "直播榜" or "直播排行" in a TikTok Shop / TikTok e-commerce context, use the ranking endpoint. When they ask about a specific livestream's detailed metrics (revenue, viewers, duration, GPM) and a livestreamId is available (or can be obtained from the ranking), use the detail endpoint.

Compute consumption rules

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

  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.