API reference / LIVE rooms / LIVE hourly ranking

LIVE hourly ranking

The hourly LIVE ranking.

GETapi.tikultra.com/v1/live/rankingHeavy · 10 credits

Upstream: /webcast/ranklist/hour/
Access: Every plan
Runs on: LeanPool · android · tiktok · 47.5.41
Client: os, app_flavour, app_version overrides
Billing: Failed calls are free
Older path: /v1/scrape/live/ranking

Authorization & parameters

x-api-keyheader · stringrequired

Your API key. Create one in API keys.

Query parameters

regionstring

Two-letter country code for egress and storefront. For example US.

citystring

A city in that region. See the supported cities list. For example miami.

Client and egress

Optional. Leave them out to run as android · tiktok · 47.5.41 from the default LeanPool context. See Clients and versions.

osstring

android or ios. For example android.

app_flavourstring

Run as tiktok, lite, lite_coin, pro, studio, shop, tv, douyin. For example tiktok.

app_versionstring

A release of that app. Defaults to the current default for (os, app_flavour). For example 47.5.41.

regionstring

Two-letter country code for egress. For example US.

citystring

A supported city in that region. For example miami.

Response

A 200 returns JSON with stable field names. Every response carries x-credits-cost, x-credits-tier and x-credits-remaining.

Response fields

Key top-level and nested fields decoded from the mobile upstream payload:

status_codeinteger

Upstream TikTok mobile status code (0 indicates success).

regionstring

Two-letter ISO 3166-1 country code associated with the item or context.

rank_typestring

Decoded rank type value.

resets_atinteger

ISO-8601 timestamp for resets.

itemsobject[]

Page of normalized records returned by this endpoint.

items[].rankinteger

Decoded rank value.

items[].room_idstring

64-bit LIVE room Snowflake identifier.

items[].hostobject

Structured host metadata.

items[].scoreinteger

Decoded score value.

items[].viewer_countinteger

Concurrent viewers currently in the LIVE room.

log_pbobject

Upstream request trace envelope from the mobile gateway.

log_pb.impr_idstring

Upstream TikTok impression / trace identifier.

Errors

Errors return a JSON body with a stable code and cost 0 credits. See Errors and retries.