RoomScope

Cập nhật lần cuối

Creator

Hồ sơ creator đã lưu, thay đổi, quan hệ follow và phân tích.

Mọi thao tác đều xác thực bằng API key (Authorization: Bearer <key>) và lỗi dùng chung envelope được mô tả trong Lỗi. Được tạo từ tài liệu OpenAPI của API.

Liệt kê các agency TikTok LIVE

GET/v1/agencies

Các agency TikTok LIVE (lấy từ hồ sơ agency công khai), tìm được theo tên hoặc handle chính thức, lọc theo khu vực và theo hồ sơ công khai, sắp xếp theo quy mô (hostCountMin), mức doanh thu (monthlyDiamondMin), mới nhất hoặc tên. Các mức là khoảng do chính TikTok đặt. Thông tin liên hệ chỉ gồm những gì agency đã công bố.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/agencies
NameTypeDescription
qOptional
stringMột phần tên agency, hoặc handle chính thức của agency.
regionOptional
stringNhóm khu vực (ví dụ VN, US+, MENA).
publicOnlyOptional
booleanChỉ các agency có hồ sơ công khai.
sortOptional
"size" | "revenue" | "recent" | "name"size, revenue, recent hoặc name.
Default: size
limitOptional
integerSố dòng tối đa. Khoảng giá trị …–200.
Default: 50
offsetOptional
integerSố dòng bỏ qua.
Default: 0

Request

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

Response

200 OK
{  "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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy một agency TikTok LIVE

GET/v1/agencies/{agency_id}

Một agency trong danh bạ, đúng như GET /v1/agencies liệt kê.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/agencies/{agency_id}
NameTypeDescription
agency_idRequired
stringID agency trên TikTok.

Request

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

Response

200 OK
{  "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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Tìm kiếm creator

GET/v1/creators

Khớp một phần chuỗi của handle hoặc tên hiển thị, không phân biệt hoa thường, nhiều follower nhất trước. q rỗng sẽ duyệt toàn bộ tập đã lưu.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/creators
NameTypeDescription
qOptional
stringHandle (có hoặc không có @) hoặc một phần tên hiển thị.
limitOptional
integerSố kết quả tối đa. Khoảng giá trị 1–100.
Default: 20

Request

curl "https://api.next.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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy hồ sơ creator

GET/v1/creators/{uid}

Hồ sơ công khai đã lưu và lịch sử các bộ đếm gần đây. Creator chưa lưu (hoặc lưu đã lâu) sẽ được tra cứu trên TikTok: nếu mất hơn vài giây, câu trả lời là 202 với status: resolving, một jobId và retryAfterSeconds (cũng có Retry-After); hỏi lại lúc đó là có hồ sơ. status: saturated (202) nghĩa là đang có quá nhiều lượt tra cứu; handle TikTok không biết trả 404 và không tra cứu lại trong mười phút; 503 resolve_unavailable nghĩa là hiện không đọc được TikTok.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Request

curl "https://api.next.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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Phân tích video của creator

GET/v1/creators/{uid}/analysis

Báo cáo tương tác chỉ tính từ các video đã lưu: tổng, trung vị, nhịp đăng. read là tối đa năm câu đơn giản, quan trọng nhất trước, mỗi câu là một code (engagement, reach, growth, cadence, posting-gap, breakout, audience-language) kèm params, để client tự diễn đạt bằng ngôn ngữ của mình; limits cho biết báo cáo không bao gồm gì và vì sao thiếu một câu.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/analysis
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Request

curl "https://api.next.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    },    "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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê thay đổi hồ sơ

GET/v1/creators/{uid}/changes

Các thay đổi handle, tên, bio và trạng thái xác minh được quan sát theo thời gian, mới nhất trước.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/changes
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Tham số query

Tham số query · GET /v1/creators/{uid}/changes
NameTypeDescription
limitOptional
integerSố thay đổi tối đa. Khoảng giá trị 1–200.
Default: 50

Request

curl "https://api.next.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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê follower của creator

GET/v1/creators/{uid}/followers

Follower đã lưu, cùng cấu trúc với following.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/followers
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Tham số query

Tham số query · GET /v1/creators/{uid}/followers
NameTypeDescription
cursorOptional
stringCursor mờ lấy từ nextCursor của trang trước.
limitOptional
integerSố entry mỗi trang.

Request

curl "https://api.next.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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê các tài khoản creator đang follow

GET/v1/creators/{uid}/following

Quan hệ follow đã lưu. Tài khoản riêng tư trả về isPrivate: true và không có entry nào.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/following
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Tham số query

Tham số query · GET /v1/creators/{uid}/following
NameTypeDescription
cursorOptional
stringCursor mờ lấy từ nextCursor của trang trước.
limitOptional
integerSố entry mỗi trang.

Request

curl "https://api.next.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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy top người tặng quà của creator

GET/v1/creators/{uid}/gifters

Người tặng quà trong các phòng LIVE của creator trong 7 hoặc 30 ngày qua, xếp theo kim cương: số quà, số phiên, quà gần nhất và creator của phòng gần nhất mà họ đã tặng. Đọc từ các phiên RoomScope đã ghi lại, nên độ phủ luôn là partial. Cần gói Pro trở lên.

Scopegifter:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/gifters
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Tham số query

Tham số query · GET /v1/creators/{uid}/gifters
NameTypeDescription
windowOptional
"7d" | "30d"7d hoặc 30d.
Default: 7d
limitOptional
integerSố dòng tối đa. Khoảng giá trị …–100.
Default: 20

Request

curl "https://api.next.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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy insight của creator

GET/v1/creators/{uid}/insights

Lịch sử handle, kim cương theo ngày trong 30 ngày qua (mới nhất trước), ảnh chụp league theo ngày và phòng LIVE của creator. liveExact là true khi điểm của ngày được đọc đúng lúc bảng reset; nếu không, liveScore là điểm cao nhất đọc được trong ngày đó. observedCoins đếm số kim cương RoomScope đã ghi trong các phiên LIVE của creator. Handle đã đổi vẫn được phân giải qua lịch sử bí danh.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/creators/{uid}/insights
NameTypeDescription
uidRequired
stringHandle của creator không kèm @ (linh.live) hoặc user id TikTok dạng số.

Request

curl "https://api.next.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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy giờ tốt nhất để lên LIVE

GET/v1/insights/best-time

Kim cương và số giờ-người tặng quà của các phiên LIVE đã ghi trong một khu vực trong windowDays ngày qua, theo ngày trong tuần (0 = thứ Hai) và giờ UTC. Tính lại mỗi ngày; cells trống khi chưa ghi nhận được gì cho khu vực đó.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/insights/best-time
NameTypeDescription
regionOptional
stringMã khu vực ISO 3166-1 alpha-2.
Default: VN

Request

curl "https://api.next.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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy mức hiện diện LIVE theo giờ

GET/v1/insights/presence

Theo từng giờ, có bao nhiêu creator có hạng đang được theo dõi của khu vực đang live, cũ nhất trước.

Scopecreator:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/insights/presence
NameTypeDescription
regionOptional
stringMã khu vực ISO 3166-1 alpha-2.
Default: VN
hoursOptional
integerLùi lại bao nhiêu giờ. Khoảng giá trị 1–168.
Default: 48

Request

curl "https://api.next.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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.
Trang này có hữu ích không?