API reference / LIVE rooms / LIVE room

LIVE room

Room state, host, viewer counts and stream metadata.

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

Upstream: /webcast/room/enter//webcast/room/info/
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/room

Authorization & parameters

x-api-keyheader · stringrequired

Your API key. Create one in API keys.

Query parameters

room_idstringone of these

The numeric LIVE room ID. For example 7705861000123456789.

usernamestringone of these

The host's @username.

urlstringone of these

A LIVE link.

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).

room_idstring

64-bit LIVE room Snowflake identifier.

stream_idstring

Active live broadcast stream identifier.

statusstring

Current lifecycle or health status.

titlestring

Decoded title value.

viewer_countinteger

Concurrent viewers currently in the LIVE room.

total_user_countinteger

Total total user count.

like_countinteger

Total like count.

hostobject

Structured host metadata.

host.uidstring

Numeric 64-bit TikTok user ID.

host.sec_uidstring

Encrypted stable account identifier used across mobile endpoints.

host.unique_idstring

Public @username handle without the leading @.

host.nicknamestring

Display name shown on the creator profile.

host.verifiedboolean

Whether the account carries a verified badge.

room_authobject

Structured room auth metadata.

room_auth.chatboolean

Whether chat is enabled or true.

room_auth.giftboolean

Whether gift is enabled or true.

room_auth.shareboolean

Whether share is enabled or true.

room_auth.diggboolean

Whether digg is enabled or true.

has_commerce_goodsboolean

Whether commerce goods is enabled or true.

started_atinteger

ISO-8601 timestamp for started.

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.

{ "status_code": 0, "room_id": "7705861000123456789", "stream_id": "2988475619283746510", "status": "live", "title": "Building 3 custom keyboards live + sound test", "viewer_count": 1842, "total_user_count": 29410, "like_count": 84200, "host": { "uid": "6970000000000000001", "sec_uid": "MS4wLjABAAAAq8V3xLm2pR9wQ8mN4vK1zH7tB2yX", "unique_id": "acme", "nickname": "Acme Studio", "verified": false }, "room_auth": { "chat": true, "gift": true, "share": true, "digg": true }, "has_commerce_goods": true, "started_at": 1794397200, "log_pb": { "impr_id": "202611120200419F8E7D6C5B4A3210" } }