Cập nhật lần cuối 1 thg 11, 2026

Creators

Stored creator profiles, changes, follow graph and analytics.

Tài liệu kỹ thuật hiện chỉ có bằng tiếng Anh.

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.

Search creators

GET/v1/creators

Handle or display-name substring, case-insensitive, most-followed first. An empty q browses the stored set.

Scopecreator:readCreditsCached read

Query parameters

Query parameters of GET /v1/creators
Name	Type	Description
`q`Optional	string	Handle (with or without `@`) or part of the display name.
`limit`Optional	integer	Maximum results. Range 1–100. Default: `20`

Request

curl "https://api.toktokdata.live/v1/creators" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Get a creator profile

GET/v1/creators/{uid}

The stored public profile and its recent history of counters.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Request

curl "https://api.toktokdata.live/v1/creators/linh.live" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Analyse a creator's videos

GET/v1/creators/{uid}/analysis

Engagement report computed from the stored videos only: totals, medians, posting cadence.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/analysis
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/analysis" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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    },    "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

List profile changes

GET/v1/creators/{uid}/changes

Handle, name, bio and verification changes observed over time, newest first.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/changes
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Query parameters

Query parameters of GET /v1/creators/{uid}/changes
Name	Type	Description
`limit`Optional	integer	Maximum changes. Range 1–200. Default: `50`

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/changes" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

List a creator's followers

GET/v1/creators/{uid}/followers

Stored followers, same shape as following.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/followers
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Query parameters

Query parameters of GET /v1/creators/{uid}/followers
Name	Type	Description
`cursor`Optional	string	Opaque cursor from `nextCursor` of the previous page.
`limit`Optional	integer	Entries per page.

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/followers" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

List accounts a creator follows

GET/v1/creators/{uid}/following

Stored follow graph. Private accounts return isPrivate: true and no entries.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/following
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Query parameters

Query parameters of GET /v1/creators/{uid}/following
Name	Type	Description
`cursor`Optional	string	Opaque cursor from `nextCursor` of the previous page.
`limit`Optional	integer	Entries per page.

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/following" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Get a creator's top gifters

GET/v1/creators/{uid}/gifters

Gifters 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.

Scopegifter:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/gifters
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Query parameters

Query parameters of GET /v1/creators/{uid}/gifters
Name	Type	Description
`window`Optional	"7d" \| "30d"	`7d` or `30d`. Default: `7d`
`limit`Optional	integer	Maximum rows. Range …–100. Default: `20`

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/gifters" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Get a creator's insights

GET/v1/creators/{uid}/insights

Handle 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.

Scopecreator:readCreditsCached read

Path parameters

Path parameters of GET /v1/creators/{uid}/insights
Name	Type	Description
`uid`Required	string	Creator handle without `@` (`linh.live`) or numeric TikTok user id.

Request

curl "https://api.toktokdata.live/v1/creators/linh.live/insights" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Get the best time to go LIVE

GET/v1/insights/best-time

Diamonds 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.

Scopecreator:readCreditsCached read

Query parameters

Query parameters of GET /v1/insights/best-time
Name	Type	Description
`region`Optional	string	ISO 3166-1 alpha-2 region code. Default: `VN`

Request

curl "https://api.toktokdata.live/v1/insights/best-time" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Get hourly LIVE presence

GET/v1/insights/presence

Per hour, how many of the region's tracked ranked creators were live, oldest first.

Scopecreator:readCreditsCached read

Query parameters

Query parameters of GET /v1/insights/presence
Name	Type	Description
`region`Optional	string	ISO 3166-1 alpha-2 region code. Default: `VN`
`hours`Optional	integer	How many hours back. Range 1–168. Default: `48`

Request

curl "https://api.toktokdata.live/v1/insights/presence" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK

{  "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

400 Invalid parameter or body; code names the problem.
401 Missing or unknown API key.
402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
403 The key lacks the scope, or the plan does not include the feature.
429 Request rate exceeded; honour Retry-After.

Trang này có hữu ích không?