Kalodata - TikTok Creator Search & Detail
This skill supports a two-step TikTok creator workflow via the Kalodata data source:
- Browse creator leaderboards to discover high-performing TikTok Shop creators.
- Fetch one creator's full profile and performance detail by .
Use the search endpoint when the user wants rankings, influencer discovery, or creator comparison. Use the detail endpoint when the user already has a
or has selected one creator from a ranking result.
Core Concepts
The creator ranking endpoint returns a paginated leaderboard filtered by
,
,
, and
. The default ranking order is by
(GMV) descending. Each creator row includes identity, audience, content views, sales volume, video/live revenue, and revenue growth rate.
The creator detail endpoint fetches
one creator by
. It returns the creator's identity, audience, revenue split, video/live metrics, product/shop counts, and contact channels. The
usually comes from the ranking response field
.
Both endpoints may reflect a statistical delay (T+1). See
for full request and response details.
Data Fields
Ranking rows include:
| Field | Description |
|---|
| creator_nickname | Creator display name |
| creator_handle | TikTok handle |
| creator_id | Creator unique ID; pass this as for detail lookup |
| creator_followers | Follower count, returned as a string |
| content_views | Total content views, returned as a string |
| sales_volumn | Sales volume; field is spelled |
| revenue | Total GMV in the requested currency |
| video_revenue | Revenue from videos |
| live_revenue | Revenue from livestreams |
| revenue_growth_rate | Revenue growth rate (%) |
Detail rows additionally include:
| Field | Description |
|---|
| creator_region / creator_status / creator_bio | Creator profile metadata |
| new_followers | New followers in the requested date window |
| unit_price | Average unit price in the requested currency |
| video_number / video_views / video_gpm | Video count, views, and GPM |
| live_number / live_views / live_gpm | Livestream count, views, and GPM |
| product_number / shop_number | Associated product and shop counts |
| creator_contact_* | Email and social contact fields; often empty |
Parameter Guide
| Parameter | Type | Required | Description |
|---|
| region | string | No | Market region code, e.g. |
| dateRange | string | No | Time window, e.g. , |
| pageNumber | integer | No | Page number, 1-5 |
| pageSize | integer | No | Page size, 5-100 |
| language | string | No | Response language, e.g. , |
| currency | string | No | Currency for monetary metrics, e.g. |
| sortField | object | No | Sorting specification; pass for default revenue ranking |
| Parameter | Type | Required | Description |
|---|
| creatorId | string | Yes | Creator unique ID from ranking field |
| region | string | No | Market region code, e.g. |
| dateRange | string | No | Time window, e.g. , |
| language | string | No | Response language, e.g. , |
| currency | string | No | Currency for monetary metrics, e.g. |
调用方式
- API 端点：
POST /kalodata/creator/rank
POST /kalodata/creator/detail
- Python 脚本：
python scripts/kalodata_creator_search.py '<JSON 参数>' [--inline]
python scripts/kalodata_creator_detail.py '<JSON 参数>' [--inline]
- 成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
输出策略（脚本默认行为）：
- 始终将完整响应写入
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-creator-<timestamp>.json
- 响应体 <= 8 KB：落盘后把完整 JSON 打印到 stdout
- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 /、最大列表字段的长度 + 前 3 条样本）
- 加 强制全量打印到 stdout（同样落盘）
读数据建议：先看摘要判断是否足够；需要具体字段时优先用
或
从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
异常情况
- 未配置API Key：环境变量未配置 ，也未配置 。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
Usage Examples
1. Browse top TikTok creators in the US
json
{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}
2. Fetch one creator's detail
json
{"creatorId":"7153432386608251946","region":"US","dateRange":"last7Day","currency":"USD"}
3. Discovery-to-detail workflow
text
Run kalodata_creator_search.py first, choose a row's creator_id, then pass that value as creatorId to kalodata_creator_detail.py.
Display Rules
- Present ranking results in a table with nickname, handle, followers, content views, sales volume, revenue, video/live revenue, and growth rate.
- Present detail results as one grouped profile: identity, audience, revenue, video, live, products/shops, and contact.
- Always label , , and when showing metrics.
- Treat and as string-typed counts; parse before numeric comparison.
- Use the exact field name .
- Show contact fields only when populated; otherwise say no contact was provided.
- Preserve ranking order unless the user explicitly requests a supported .
Important Limitations
- Ranking is not keyword search; it browses leaderboards by region and time window.
- Detail requires ; it cannot find a creator by nickname or handle alone.
- The ranking response does not include total/page count; paginate until a page returns fewer than items.
- is limited to 1-5 and is limited to 5-100.
- Transient upstream errors may appear as with a Kalodata HTTP 554 message. Retry the same parameters once or twice; do not change parameters automatically.
- Use the matching Kalodata product/video/shop/livestream skills for non-creator entities.
User Expression & Scenario Quick Reference
Applicable -- TikTok creator ranking or creator profile lookup:
| User Says | Scenario |
|---|
| "TikTok达人排行榜", "TikTok网红榜" | Creator ranking lookup |
| "TikTok带货达人榜", "top TikTok creators" | Creator leaderboard by region |
| "近7天TikTok达人榜" | Time-windowed ranking |
| "TikTok达人详情", "达人主页数据" | Creator detail lookup |
| "达人联系方式", "creator contact" | Contact channels |
| "kalodata creator search/detail" | Direct data source reference |
Not applicable -- Needs beyond TikTok creators:
- TikTok product/video/shop/livestream rankings or details
- Amazon / Shopify / 1688 / other platforms' creator or product data
- TikTok ad campaign management or content creation
积分消耗规则
每次调用消耗 7.0 积分。
用户会因积分消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。
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
. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.