Last updated
Creators
Stored creator profiles, changes, follow graph and analytics.
Every operation authenticates with an API key (Authorization: Bearer <key>) and errors use the shared envelope described in Errors. Generated from the API’s OpenAPI document.
List TikTok LIVE agencies
/v1/agenciesTikTok LIVE agencies (from their public agency profiles), searchable by name or official handle, by region and by public profile, sorted by size (hostCountMin), revenue band (monthlyDiamondMin), newest or name. Bands are TikTok's own ranges. Contact details show only what the agency published.
Query parameters
| Name | Type | Description |
|---|---|---|
qOptional | string | Part of the agency name, or its official handle. |
regionOptional | string | Region bucket (e.g. VN, US+, MENA). |
publicOnlyOptional | boolean | Only agencies with a public profile. |
sortOptional | "size" | "revenue" | "recent" | "name" | size, revenue, recent or name.Default: size |
limitOptional | integer | Maximum rows. Range …–200. Default: 50 |
offsetOptional | integer | Rows to skip. Default: 0 |
Request
curl "https://api.next.toktokdata.live/v1/agencies" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "agencies": [ { "agencyId": "108474", "name": "Look Corporation", "regions": [ "KR" ], "onboardedOn": "2025-03-01", "official": { "uid": "7012345678901234567", "handle": "look.corp", "nickname": "Look Corporation", "avatarUrl": null, "followers": 12500 }, "intro": "A TikTok LIVE agency based in Korea.", "services": [ "1_on_1_support", "live_skills_training" ], "contact": { "website": "https://example.com" }, "hostCountBand": "101-200", "agentCountBand": "11-50", "monthlyDiamondBand": "1M-5M", "hostCountMin": 101, "monthlyDiamondMin": 1000000, "hasPublicProfile": true, "lastSeenAt": "2026-10-24T05:34:33.738Z" } ], "total": 1, "offset": 0 }, "provenance": { "observedAt": "2026-10-24T05:34:33.738Z", "freshness": "stale", "source": "public_creator_profile", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "agency-directory-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a TikTok LIVE agency
/v1/agencies/{agency_id}One agency of the directory, as GET /v1/agencies lists it.
Path parameters
| Name | Type | Description |
|---|---|---|
agency_idRequired | string | TikTok agency id. |
Request
curl "https://api.next.toktokdata.live/v1/agencies/agency_id" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "agencyId": "108474", "name": "Look Corporation", "regions": [ "KR" ], "onboardedOn": "2025-03-01", "official": { "uid": "7012345678901234567", "handle": "look.corp", "nickname": "Look Corporation", "avatarUrl": null, "followers": 12500 }, "intro": "A TikTok LIVE agency based in Korea.", "services": [ "1_on_1_support", "live_skills_training" ], "contact": { "website": "https://example.com" }, "hostCountBand": "101-200", "agentCountBand": "11-50", "monthlyDiamondBand": "1M-5M", "hostCountMin": 101, "monthlyDiamondMin": 1000000, "hasPublicProfile": true, "lastSeenAt": "2026-10-24T05:34:33.738Z" }, "provenance": { "observedAt": "2026-10-24T05:34:33.738Z", "freshness": "stale", "source": "public_creator_profile", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "agency-directory-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Search creators
/v1/creatorsHandle or display-name substring, case-insensitive, most-followed first. An empty q browses the stored set.
Query parameters
| Name | Type | Description |
|---|---|---|
qOptional | string | Handle (with or without @) or part of the display name. |
limitOptional | integer | Maximum results. Range 1–100. Default: 20 |
Request
curl "https://api.next.toktokdata.live/v1/creators" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "query": "linh.live", "results": [ { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "displayName": "Linh Live", "region": "VN", "avatarUrl": null, "followerCount": 123456, "verified": true } ] }, "provenance": { "observedAt": "2026-11-01T10:36:44.935Z", "freshness": "near_realtime", "source": "public_creator_profile", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "creators-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a creator profile
/v1/creators/{uid}The stored public profile and its recent history of counters. A creator not stored yet (or stored long ago) is looked up on TikTok: when that takes longer than a few seconds the answer is 202 with status: resolving, a jobId and retryAfterSeconds (also Retry-After); ask again then and the profile is there. status: saturated (202) means too many lookups are running; a handle TikTok does not know is a 404 and is not looked up again for ten minutes; 503 resolve_unavailable means TikTok could not be read right now.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "creator": { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "secUid": null, "displayName": "Linh Live", "region": "VN", "language": null, "signature": "Daily LIVE from Hanoi", "avatarUrl": null, "followerCount": 123456, "followingCount": 321, "awemeCount": 3, "totalFavorited": 9876543, "favoritingCount": null, "verified": true, "customVerify": null, "enterpriseVerifyReason": null, "instagramId": null, "youtubeChannelId": null, "twitterId": null, "firstSeenAt": "2026-10-02T10:51:44.935Z", "lastRefreshedAt": "2026-11-01T10:36:44.935Z", "history": [] } }, "provenance": { "observedAt": "2026-11-01T10:36:44.935Z", "freshness": "near_realtime", "source": "public_creator_profile", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "creators-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Analyse a creator's videos
/v1/creators/{uid}/analysisEngagement report computed from the stored videos only: totals, medians, posting cadence. read is up to five plain sentences, most telling first, each a code (engagement, reach, growth, cadence, posting-gap, breakout, audience-language) with its params, for the client to word in its own language; limits says what the report cannot cover and why a sentence is missing.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/analysis" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "creator": { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "displayName": "Linh Live", "avatarUrl": null, "region": "VN", "verified": true, "followerCount": 123456, "followingCount": 321, "awemeCount": 3, "totalFavorited": 9876543, "firstSeenAt": "2026-10-02T10:51:44.935Z", "lastRefreshedAt": "2026-11-01T10:36:44.935Z" }, "sample": { "videosAnalyzed": 3, "oldestVideoAt": "2026-10-29T10:51:44.935Z", "newestVideoAt": "2026-10-31T10:51:44.935Z", "spanDays": 2, "shareOfCatalog": 1 }, "engagement": { "totalPlays": 60000, "totalLikes": 6000, "totalComments": 600, "totalShares": 0, "avgPlays": 20000, "medianPlays": 20000, "avgLikes": 2000, "avgComments": 200, "avgShares": 0, "engagementRate": 0.11, "likeRate": 0.1, "commentRate": 0.01, "shareRate": 0, "viewsPerFollower": 0.162 }, "read": [ { "code": "engagement", "params": { "rate": 0.11, "band": "typical" } }, { "code": "reach", "params": { "ratio": 0.162, "band": "most-followers" } }, { "code": "growth", "params": { "delta": 1840, "rate": 0.0371, "days": 29.8, "direction": "up" } }, { "code": "cadence", "params": { "postsPerWeek": 7, "busiestWeekday": 4 } } ], "cadence": { "postsPerWeek": 7, "avgDaysBetweenPosts": 1, "longestGapDays": 1, "busiestWeekday": 4, "postsByWeekday": [ 0, 0 ] }, "topByPlays": [ { "videoId": "7990000000000000003", "description": "Video 3", "createTime": "2026-10-29T10:51:44.935Z", "playCount": 30000, "diggCount": 3000, "commentCount": 300, "shareCount": null, "engagementRate": 0.11 }, { "videoId": "7990000000000000002", "description": "Video 2", "createTime": "2026-10-30T10:51:44.935Z", "playCount": 20000, "diggCount": 2000, "commentCount": 200, "shareCount": null, "engagementRate": 0.11 } ], "topByEngagement": [ { "videoId": "7990000000000000001", "description": "Video 1", "createTime": "2026-10-31T10:51:44.935Z", "playCount": 10000, "diggCount": 1000, "commentCount": 100, "shareCount": null, "engagementRate": 0.11 }, { "videoId": "7990000000000000002", "description": "Video 2", "createTime": "2026-10-30T10:51:44.935Z", "playCount": 20000, "diggCount": 2000, "commentCount": 200, "shareCount": null, "engagementRate": 0.11 } ], "audience": null, "growth": null, "limits": [ { "code": "thin-video-sample", "message": "Only 3 video(s) analysed — too few to describe the account's typical performance." }, { "code": "single-observation", "message": "This account has been observed only once, so no follower growth can be shown yet." } ] }, "provenance": { "observedAt": "2026-11-01T10:36:44.935Z", "freshness": "near_realtime", "source": "derived_creator_analysis", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "analysis-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List profile changes
/v1/creators/{uid}/changesHandle, name, bio and verification changes observed over time, newest first.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Query parameters
| Name | Type | Description |
|---|---|---|
limitOptional | integer | Maximum changes. Range 1–200. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/changes" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "changes": [] }, "provenance": { "observedAt": "2026-10-02T10:51:44.935Z", "freshness": "stale", "source": "public_creator_profile", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "creators-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List a creator's followers
/v1/creators/{uid}/followersStored followers, same shape as following.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Query parameters
| Name | Type | Description |
|---|---|---|
cursorOptional | string | Opaque cursor from nextCursor of the previous page. |
limitOptional | integer | Entries per page. |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/followers" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "direction": "following", "entries": [], "nextCursor": null, "hasMore": false, "totalReported": null, "storedCount": 0, "isPrivate": false }, "provenance": { "observedAt": "2026-11-01T11:18:49.084Z", "freshness": "stale", "source": "public_follow_graph", "sourceKind": "derived", "coverageStatus": "not-covered", "methodologyVersion": "follow-list-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List accounts a creator follows
/v1/creators/{uid}/followingStored follow graph. Private accounts return isPrivate: true and no entries.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Query parameters
| Name | Type | Description |
|---|---|---|
cursorOptional | string | Opaque cursor from nextCursor of the previous page. |
limitOptional | integer | Entries per page. |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/following" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "tiktokUserId": "990000000000000001", "uniqueId": "linh.live", "direction": "following", "entries": [], "nextCursor": null, "hasMore": false, "totalReported": null, "storedCount": 0, "isPrivate": false }, "provenance": { "observedAt": "2026-11-01T11:18:49.084Z", "freshness": "stale", "source": "public_follow_graph", "sourceKind": "derived", "coverageStatus": "not-covered", "methodologyVersion": "follow-list-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a creator's top gifters
/v1/creators/{uid}/giftersGifters of the creator's LIVE rooms over the last 7 or 30 days, by diamonds: gift count, sessions, last gift and the creator of the last room they gifted in. Read from the sessions RoomScope recorded, so coverage is always partial. Needs the Pro plan or above.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Query parameters
| Name | Type | Description |
|---|---|---|
windowOptional | "7d" | "30d" | 7d or 30d.Default: 7d |
limitOptional | integer | Maximum rows. Range …–100. Default: 20 |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/gifters" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "creatorUid": "7012345678901234567", "uniqueId": "linh.live", "window": "7d", "gifters": [ { "gifterUserId": "6987001122334455667", "gifterUniqueId": "minh.fan", "gifterNickname": "Minh", "avatarUrl": null, "diamondTotal": 18450, "giftCount": 312, "sessions": 4, "lastGiftAt": "2026-11-02T15:41:07.512Z", "lastRoomCreator": "linh.live" } ] }, "provenance": { "observedAt": "2026-11-02T15:41:07.512Z", "freshness": "historical", "source": "platform_observed_gifter_events", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "gifters-observed-v1", "window": { "from": "2026-10-27T04:00:00.000Z", "to": "2026-11-03T04:00:00.000Z", "label": "7d" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a creator's insights
/v1/creators/{uid}/insightsHandle history, daily diamonds of the last 30 days (newest first), daily league snapshots and the creator's LIVE room. liveExact is true when the day's score was read at the board reset; otherwise liveScore is the highest score read that day. observedCoins counts diamonds RoomScope recorded in the creator's LIVE sessions. A handle that changed still resolves through the alias history.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Request
curl "https://api.next.toktokdata.live/v1/creators/linh.live/insights" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "creator": { "uid": "6990000000000000001", "uniqueId": "linh.live" }, "aliases": [ { "uniqueId": "linh.live", "firstSeenAt": "2026-10-12T09:15:02.118Z", "lastSeenAt": "2026-11-01T14:02:41.530Z" }, { "uniqueId": "linh.official", "firstSeenAt": "2026-09-30T11:40:19.004Z", "lastSeenAt": "2026-10-12T08:55:47.912Z" } ], "daily": [ { "boardDay": "2026-10-31", "countryCode": "VN", "tiktokScore": 184250, "observedCoins": 171932, "liveScore": 184250, "liveExact": true, "leagueClass": "B2" }, { "boardDay": "2026-10-30", "countryCode": "VN", "tiktokScore": 97410, "observedCoins": null, "liveScore": 97410, "liveExact": false, "leagueClass": "B2" } ], "league": [ { "day": "2026-10-31", "leagueClass": "B2", "leagueRank": 14, "leagueCountry": "VN", "followers": 412880 } ], "roomOwner": { "roomId": "7432000000000000001", "ownerUid": "6990000000000000001", "ownerUniqueId": "linh.live", "claimantUid": null, "reason": "claim_confirmed", "checkedAt": "2026-11-01T14:00:03.221Z" } }, "provenance": { "observedAt": "2026-11-01T14:02:41.530Z", "freshness": "near_realtime", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "creator-analytics-v1", "window": { "from": "2026-10-02T14:02:41.530Z", "to": "2026-11-01T14:02:41.530Z", "label": "30d" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get the best time to go LIVE
/v1/insights/best-timeDiamonds and gifter-hours of a region's recorded LIVE sessions over the last windowDays days, per weekday (0 = Monday) and UTC hour. Recomputed daily; cells is empty while nothing has been recorded for the region.
Query parameters
| Name | Type | Description |
|---|---|---|
regionOptional | string | ISO 3166-1 alpha-2 region code. Default: VN |
Request
curl "https://api.next.toktokdata.live/v1/insights/best-time" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "region": "VN", "windowDays": 28, "computedAt": "2026-11-01T01:00:04.870Z", "cells": [ { "weekday": 0, "hour": 12, "diamonds": 418230, "gifterHours": 1874 }, { "weekday": 0, "hour": 13, "diamonds": 652910, "gifterHours": 2410 }, { "weekday": 0, "hour": 14, "diamonds": 701455, "gifterHours": 2689 } ] }, "provenance": { "observedAt": "2026-11-01T01:00:04.870Z", "freshness": "near_realtime", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "creator-analytics-v1", "window": { "from": "2026-10-04T01:00:04.870Z", "to": "2026-11-01T01:00:04.870Z", "label": "28d" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get hourly LIVE presence
/v1/insights/presencePer hour, how many of the region's tracked ranked creators were live, oldest first.
Query parameters
| Name | Type | Description |
|---|---|---|
regionOptional | string | ISO 3166-1 alpha-2 region code. Default: VN |
hoursOptional | integer | How many hours back. Range 1–168. Default: 48 |
Request
curl "https://api.next.toktokdata.live/v1/insights/presence" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "region": "VN", "hours": 48, "points": [ { "hourStart": "2026-11-01T12:00:00.000Z", "liveCreators": 214, "trackedCreators": 1630 }, { "hourStart": "2026-11-01T13:00:00.000Z", "liveCreators": 251, "trackedCreators": 1642 }, { "hourStart": "2026-11-01T14:00:00.000Z", "liveCreators": 268, "trackedCreators": 1655 } ] }, "provenance": { "observedAt": "2026-11-01T14:05:01.402Z", "freshness": "near_realtime", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "creator-analytics-v1", "window": { "from": "2026-10-30T14:05:01.402Z", "to": "2026-11-01T14:05:01.402Z", "label": "48h" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.