TikTok LIVE Rankings
Leaderboards
Manage leaderboards within the TikTok LIVE Rankings API. This section covers endpoints for working with leaderboards including retrieval, creation, and management operations.
Get available dates
Retrieve the list of dates that have leaderboard data for a given rank type and region.
Requests to catalogue endpoints do NOT count towards normal API limits.
Path Parameters
The region to query (or "WW" for worldwide).
Query Parameters
League level filter (e.g. "D5", "A1"). Required for RANKING_LEAGUE, must not be provided for other rank types.
Responses
Get available rankings
Returns the available ranking types and league tiers for each tracked region, based on each leaderboard's most recent day of data in the ranking service (boards with no data for several days age out of the catalog).
Requests to catalogue endpoints do NOT count towards normal API limits.
Responses
Get leaderboard
Retrieve the most recent leaderboard snapshot for a given rank type, region, and date.
Requests to catalogue endpoints do NOT count towards normal API limits.
Path Parameters
The region to query (or "WW" for worldwide).
Query Parameters
The UTC date to retrieve the snapshot for (e.g. "2026-03-09"). Omitted = the board's most recent snapshot (matching what the catalog advertises).
Optional league level filter (e.g. "D5", "A1"). Only applicable to RANKING_LEAGUE.
Responses
Diamond totals of the board for date, the day before, and the seven-day average; every field null unless the board scores in diamonds (DAILY_RANK).
Creators live when this snapshot was taken: for a region, its rows whose is_live.status is true; for the worldwide merge (a capped list), the day's deduplicated live count across every region's daily board, so only DAILY_RANK carries it.
Get user day history
Retrieve every intraday datapoint recorded for a creator on a given board for a single UTC date, oldest first. Consecutive points carry the day's cumulative score as it grew — the deltas between them are the creator's per-interval earnings (e.g. for an earnings-per-hour view).
Requests to catalogue endpoints do NOT count towards normal API limits.
Path Parameters
The rank type identifier (e.g. "DAILY_RANK", "RANKING_LEAGUE").
The leaderboard region (e.g. "US").
TikTok numeric user id of the creator.
The UTC rank date to retrieve (e.g. "2026-03-01").
Responses
The requested UTC rank date.
Get user history
Retrieve a creator's daily standing on a given board over a UTC date range, oldest first.
Requests to catalogue endpoints do NOT count towards normal API limits.
Path Parameters
The leaderboard region (e.g. "US").
TikTok numeric user id of the creator.
Query Parameters
Start of the UTC date range, inclusive (e.g. "2026-03-01").
End of the UTC date range, inclusive (e.g. "2026-03-31").
Responses
Get user leaderboards over timespan
Discovery: The leaderboards a creator appears on within a UTC date range, returned as a map of region to rank_types.
Rate limited to 30 requests/min. Does NOT count towards normal API limits.
Path Parameters
TikTok numeric user id of the creator.
Query Parameters
Start of the UTC date range, inclusive (e.g. "2026-03-01").
End of the UTC date range, inclusive (e.g. "2026-03-31").
Responses
region -> rank_names the creator appeared on (e.g. "DAILY_RANK", "SALE_RANK").
Get user streams
Retrieve the list of Room IDs in which a creator was observed in the Top 99 of the given TikTok LIVE board over a UTC date range, newest first, with their estimated earnings across each stream (daily board only; every other board reports null earnings).
Requests to catalogue endpoints do NOT count towards normal API limits.
Path Parameters
The leaderboard region (e.g. "US").
TikTok numeric user id of the creator.
Query Parameters
Start of the UTC date range, inclusive (e.g. "2026-03-01").
End of the UTC date range, inclusive (e.g. "2026-03-31").
Responses
Start of the UTC date range, inclusive.
End of the UTC date range, inclusive.
Newest first.