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
creatorId.
Use the search endpoint when the user wants rankings, influencer discovery, or creator comparison. Use the detail endpoint when the user already has a creatorId or has selected one creator from a ranking result.
Core Concepts
The creator ranking endpoint returns a paginated leaderboard filtered by region, dateRange, language, and currency. The default ranking order is by revenue (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 creatorId. It returns the creator's identity, audience, revenue split, video/live metrics, product/shop counts, and contact channels. The creatorId usually comes from the ranking response field creator_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 |
|---|---|
| creator_nickname | Creator display name |
| creator_handle | TikTok handle |
| creator_id | Creator unique ID; pass this as creatorId 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 volumn |
| 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
Creator ranking (/kalodata/creator/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_ids | array | No | Category ID list filter |
| shop_id | string | No | Shop ID filter |
| revenue_range | string | No | Revenue / GMV range filter |
| creator_type | string | No | Creator type filter |
| followers_range | string | No | Follower range filter |
| engagement_rate | string | No | Engagement-rate filter |
| sortField | object | No | Sorting specification; pass {} for default revenue ranking |
Creator detail (/kalodata/creator/detail)
| Parameter | Type | Required | Description |
|---|---|---|---|
| creatorId | string | Yes | Creator unique ID from ranking field creator_id |
| shop_id | string | No | Shop ID filter |
| category_ids | array | No | Category ID list filter |
| 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/creator/rankorPOST /kalodata/creator/detail(for full parameters/responses/error codes seereferences/api.md） - Python script：
python scripts/kalodata_creator_search.py '<JSON 参数>' [--inline]orpython scripts/kalodata_creator_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 try successive probes by changing keywords, paging, or changing the zip code; 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-creator-<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 task;writing to /tmp is prohibited, and 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, 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 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, 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. Browse top TikTok creators in the US
{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}
2. Fetch one creator's detail
{"creatorId":"7153432386608251946","region":"US","dateRange":"last7Day","currency":"USD"}
3. Discovery-to-detail workflow
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
dateRange,region, andcurrencywhen showing metrics. - Treat
creator_followersandcontent_viewsas string-typed counts; parse before numeric comparison. - Use the exact field name
sales_volumn. - Show contact fields only when populated; otherwise say no contact was provided.
- 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.
- Detail requires
creatorId; 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
pageSizeitems. pageNumberis limited to 1-5 andpageSizeis limited to 5-100.- Transient upstream errors may appear as
errcode 501with 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 creator leaderboard", "TikTok influencer ranking" | Creator ranking lookup |
| "TikTok sales creator leaderboard", "top TikTok creators" | Creator leaderboard by region |
| "TikTok creator leaderboard for the last 7 days" | Time-windowed ranking |
| "TikTok creator details", "creator profile data" | Creator detail lookup |
| "creator contact information", "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
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:
- 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.