RoomScope

최종 업데이트

랭킹

보드, 지역, 기간별 공식 랭킹 보드.

모든 작업은 API key로 인증하며 (Authorization: Bearer <key>) 오류 응답은 다음 문서에서 설명하는 공통 오류 형식을 따릅니다: 오류. 이 페이지는 API의 OpenAPI 문서에서 생성되었습니다.

보드의 일별 커트라인 조회

GET/v1/rankings/day-bars

최근 days일의 보드 일자별로: 보드에 오른 크리에이터 수, 보드의 최저 점수(보드에 들기 위한 커트라인)와 최고 점수(RoomScope가 일일 초기화 전에 관측한 마지막 완전한 보드에서 읽음), 그리고 그날 읽은 완전한 보드 수. daily와 리그 보드(league_a1~league_d5)가 대상입니다.

스코프rank:read크레딧캐시 조회

쿼리 파라미터

쿼리 파라미터 · GET /v1/rankings/day-bars
NameTypeDescription
regionOptional
string지역 코드.
Default: VN
boardOptional
stringdaily 또는 리그 보드.
Default: daily
daysOptional
integer조회할 과거 일수. 범위 …–90.
Default: 30

요청

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

응답

200 OK
{  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

보드의 지난 기간 목록 조회

GET/v1/rankings/history

한 보드의 완료된 기간 목록으로, 요금제의 기록 보관 기간 안에서 최신순으로 반환됩니다.

스코프rank:read크레딧캐시 조회

쿼리 파라미터

쿼리 파라미터 · GET /v1/rankings/history
NameTypeDescription
boardRequired
string보드 키: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly(shop:read 필요) 또는 리그 보드 league_a1 … league_d5.
regionOptional
stringISO 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"

응답

200 OK
{  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

마스킹된 행의 LIVE 합계 조회

GET/v1/rankings/masked/{ref}

보드가 반환한 maskedRef로 마스킹된 보드 행의 30일간 LIVE 합계(세션 수, 방송 시간(초), 평균 최고 시청자 수)를 반환합니다. 크리에이터의 신원은 절대 포함되지 않으며, 이름이 있는 행과 대조할 수 있는 일별·세션별 시계열도 포함되지 않습니다. ref는 그것을 받은 워크스페이스에서만 작동하며, 보드를 읽을 때마다 새 ref가 발급됩니다.

스코프rank:read크레딧캐시 조회

경로 파라미터

경로 파라미터 · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
string마스킹된 보드 행의 maskedRef.

요청

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

응답

200 OK
{  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

공식 보드 조회

GET/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입니다.

스코프rank:read크레딧캐시 조회

쿼리 파라미터

쿼리 파라미터 · GET /v1/rankings/official
NameTypeDescription
boardRequired
string보드 키: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly(shop:read 필요) 또는 리그 보드 league_a1 … league_d5.
regionOptional
stringISO 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"

응답

200 OK
{  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

지원 지역 목록 조회

GET/v1/rankings/regions

현재 관측된 보드가 있는 지역과 표시용 라벨. 하루 동안 캐시하세요.

스코프rank:read크레딧캐시 조회

요청

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

응답

200 OK
{  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.
이 페이지가 도움이 되었나요?