최종 업데이트
랭킹
보드, 지역, 기간별 공식 랭킹 보드.
모든 작업은 API key로 인증하며 (Authorization: Bearer <key>) 오류 응답은 다음 문서에서 설명하는 공통 오류 형식을 따릅니다: 오류. 이 페이지는 API의 OpenAPI 문서에서 생성되었습니다.
보드의 일별 커트라인 조회
/v1/rankings/day-bars최근 days일의 보드 일자별로: 보드에 오른 크리에이터 수, 보드의 최저 점수(보드에 들기 위한 커트라인)와 최고 점수(RoomScope가 일일 초기화 전에 관측한 마지막 완전한 보드에서 읽음), 그리고 그날 읽은 완전한 보드 수. daily와 리그 보드(league_a1~league_d5)가 대상입니다.
쿼리 파라미터
| Name | Type | Description |
|---|---|---|
regionOptional | string | 지역 코드. Default: VN |
boardOptional | string | daily 또는 리그 보드.Default: daily |
daysOptional | integer | 조회할 과거 일수. 범위 …–90. Default: 30 |
요청
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"응답
{ "data": { "region": "VN", "board": "daily", "days": [ { "boardDay": "2026-11-06", "dayEnd": "2026-11-06T17:00:00.000Z", "leagueClass": null, "entryCount": 99, "minScore": 23150, "maxScore": 880338, "boardCount": 12 } ] }, "provenance": { "observedAt": "2026-11-07T09:00:00.000Z", "freshness": "near_realtime", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "board-day-bar-v1", "window": { "from": "2026-10-09", "to": "2026-11-07", "label": "30d" } }}오류
400파라미터 또는 본문이 잘못되었습니다.code에 문제가 표시됩니다.401API key가 없거나 알 수 없는 key입니다.402워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다.resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
보드의 지난 기간 목록 조회
/v1/rankings/history한 보드의 완료된 기간 목록으로, 요금제의 기록 보관 기간 안에서 최신순으로 반환됩니다.
쿼리 파라미터
| Name | Type | Description |
|---|---|---|
boardRequired | string | 보드 키: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly(shop:read 필요) 또는 리그 보드 league_a1 … league_d5. |
regionOptional | string | ISO 3166-1 alpha-2 지역 코드. Default: VN |
cursorOptional | string | 이전 페이지의 nextCursor에서 받은 불투명 커서. |
limitOptional | integer | 페이지당 기간 수. 범위 1–24. Default: 24 |
leagueTierOptional | string | 리그 등급 필터, A1 … D5. |
요청
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"응답
{ "data": { "board": "daily", "region": "VN", "periods": [ { "periodKey": "2026-10-31", "observedAt": "2026-11-01T10:46:44.935Z", "coverageStatus": "observed", "publishable": true, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": false, "roomId": null, "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null } ] } ], "nextCursor": null, "hasMore": false, "historyWindowDays": 365, "historyTruncated": false }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}오류
400파라미터 또는 본문이 잘못되었습니다.code에 문제가 표시됩니다.401API key가 없거나 알 수 없는 key입니다.402워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다.resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
마스킹된 행의 LIVE 합계 조회
/v1/rankings/masked/{ref}보드가 반환한 maskedRef로 마스킹된 보드 행의 30일간 LIVE 합계(세션 수, 방송 시간(초), 평균 최고 시청자 수)를 반환합니다. 크리에이터의 신원은 절대 포함되지 않으며, 이름이 있는 행과 대조할 수 있는 일별·세션별 시계열도 포함되지 않습니다. ref는 그것을 받은 워크스페이스에서만 작동하며, 보드를 읽을 때마다 새 ref가 발급됩니다.
경로 파라미터
| Name | Type | Description |
|---|---|---|
refRequired | string | 마스킹된 보드 행의 maskedRef. |
요청
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"응답
{ "data": { "sessionsSummary": { "sessions": 6, "liveSeconds": 31400, "averagePeakViewers": 1640 } }, "provenance": { "observedAt": "2026-11-02T13:05:11.000Z", "freshness": "historical", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "masked-creator-v3", "window": { "from": "2026-10-04T08:00:00.000Z", "to": "2026-11-03T08:00:00.000Z", "label": "30d" } }}오류
400파라미터 또는 본문이 잘못되었습니다.code에 문제가 표시됩니다.401API key가 없거나 알 수 없는 key입니다.402워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다.resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
공식 보드 조회
/v1/rankings/official한 지역의 보드 하나를 TikTok이 게시한 그대로 반환합니다. 보드는 커버리지가 기준을 통과한 뒤에만 재현됩니다. 항목을 표시하기 전에 publishable과 coverage를 확인하세요. 플랜이 공개하는 범위를 넘는 항목은 rank와 score를 유지하지만 masked: true로 반환되며, 신원 정보가 없고(creatorUid, avatarUrl, roomId는 null) 이를 공개하는 플랜이 unmaskTier에 담깁니다. maskedRef로 /v1/rankings/masked/{ref}에서 LIVE 합계를 읽을 수 있습니다. 마스킹된 항목은 이전 위치를 드러낼 수 있으므로 movement, previousRank, sparkline도 null입니다. 현재 기간에는 그 외 모든 항목에 sparkline이 붙습니다. 이는 최근 7개 완료 기간 각각의 점수로, 오래된 순서이며 보드에 없던 기간은 null입니다.
쿼리 파라미터
| Name | Type | Description |
|---|---|---|
boardRequired | string | 보드 키: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly(shop:read 필요) 또는 리그 보드 league_a1 … league_d5. |
regionOptional | string | ISO 3166-1 alpha-2 지역 코드. Default: VN |
periodOptional | "current" | "history" | current는 진행 중인 기간, history는 가장 최근에 완료된 기간입니다.Default: current |
limitOptional | integer | 최대 항목 수. 범위 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | 지금 방송 중인 크리에이터만. Default: false |
leagueTierOptional | string | 리그 등급 필터, A1 … D5. |
요청
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"응답
{ "data": { "board": { "kind": "official", "board": "daily", "region": "VN", "periodKey": "2026-10-31", "resetAt": null, "publishable": true, "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": true, "roomId": "7990000000000000001", "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 812000, 846500, 901200, 955000, 1010300, 99000 ] }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 803880, 838035, 892188, 945450, 1000197, 97020 ] } ] } }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": { "from": null, "to": null, "label": "daily" } }}오류
400파라미터 또는 본문이 잘못되었습니다.code에 문제가 표시됩니다.401API key가 없거나 알 수 없는 key입니다.402워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다.resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
지원 지역 목록 조회
/v1/rankings/regions현재 관측된 보드가 있는 지역과 표시용 라벨. 하루 동안 캐시하세요.
요청
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"응답
{ "data": { "regions": [ { "region": "VN", "label": "VN · Vietnam", "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "boards": [ "daily" ], "notOfferedBoards": [] } ] }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}오류
400파라미터 또는 본문이 잘못되었습니다.code에 문제가 표시됩니다.401API key가 없거나 알 수 없는 key입니다.402워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다.resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.