TikTok Public LIVE Room Metadata

TikTok Public LIVE Room Metadata reads public TikTok LIVE room metadata for supplied usernames or canonical LIVE URLs. When the public route exposes a current room state, it returns room identity, title, live status, viewer count, cover, and host metadata. It is a point-in-time metadata Actor, not a live-stream capture or event API.

Get started

1. Open the Actor Store page and select Try for free or open the Input tab.
2. Supply at least one entry in usernames or liveUrls; both lists accept up to five items.
3. Keep maxUsers at 5 or lower. Enable includeDiagnostics if you want offline or blocked broadcasters written as minimal dataset rows.
4. Start the Actor, open the dataset, and export rows as JSON, CSV, or Excel. Open Run summary (OUTPUT_SUMMARY) to see how many rooms were live and how many diagnostics were written.

Input

Provide at least one username or LIVE URL. The other fields are optional; the defaults below are ready to use. Unsupported fields and out-of-range values are rejected before requests start.

Field	Type	Required?	Default	Meaning
usernames	string array	Conditional	Not supplied	Public TikTok usernames without @, up to five entries.
liveUrls	string array	Conditional	Not supplied	Canonical public HTTPS TikTok LIVE URLs, up to five entries.
maxUsers	integer	Optional	5	Maximum unique broadcasters processed after usernames and URL hosts are combined, from 1 to 5.
includeDiagnostics	boolean	Optional	false	Write minimal {url,error,errorCode,scrapedAt} rows for blocked, offline, or failed room lookups.
requestTimeoutSecs	integer	Optional	15	Bounded timeout for each public page or reader request, from 10 to 120 seconds.
maxRequestRetries	integer	Optional	1	Retries only connection failures without an HTTP response, from 0 to 2. HTTP errors and access challenges are never retried.
requestDelayMs	integer	Optional	250	Polite delay before each broadcaster after the first, from 0 to 5,000 ms.
proxyConfiguration	object	Optional	Not supplied	Optional Apify Proxy or custom HTTP(S) proxy. Proxy use does not bypass access controls.
fixturePath	string	Optional	Not supplied	QA-only relative path below test/fixtures, up to 240 characters. Fixture mode is explicit and never used as a live fallback.

Full default input; supply a username or LIVE URL before running:

{
  "maxUsers": 5,
  "includeDiagnostics": false,
  "requestTimeoutSecs": 15,
  "maxRequestRetries": 1,
  "requestDelayMs": 250
}

The Actor resolves each broadcaster through a public LIVE metadata route and normalizes usernames and URLs before deduplication. It does not join the room, download video segments, or subscribe to chat or gift events.

Output

The dataset can contain two row shapes. A room record describes a broadcaster whose public room state was available. A diagnostic row is written only when includeDiagnostics is true and the broadcaster was offline, blocked, or failed; it contains only url, error, errorCode, and scrapedAt. The saved 2026-10-25 run had diagnostics enabled and produced one room record plus four offline diagnostic rows.

Field	Type	Availability	Meaning
sourceUrl	string	In a room record	Public LIVE URL.
hostUsername	string	In a room record	Public broadcaster username.
hostUserId	string	In a room record when exposed	Public broadcaster ID.
hostDisplayName	string	In a room record when exposed	Public broadcaster display name.
roomId	string	In a room record	Public LIVE room identifier.
liveTitle	string	In a room record when exposed	Public LIVE room title.
liveStatus	string	In a room record	Public room status; a usable room record requires a live status such as 2.
currentViewers	integer	In a room record when exposed	Public current viewer count at collection time.
coverUrl	string	In a room record when exposed	Public room cover URL.
eventStreamAvailable	boolean	In a room record	Always false; this metadata-only Actor does not subscribe to LIVE events.
eventStreamStatus	string	In a room record	Explicit event-stream limitation.
source	string	In a room record	Provenance source label, tiktok.com.
scrapedAt	string	Always	UTC record timestamp.
url	string	In a diagnostic row	Requested LIVE URL.
error	string	In a diagnostic row	Bounded diagnostic message.
errorCode	string	In a diagnostic row	Stable diagnostic code, such as OFFLINE_OR_NO_ROOM_STATE or ACCESS_BLOCK.

The first example is the real room record from the 2026-10-25 run:

{
  "sourceUrl": "https://www.tiktok.com/@aljazeeraenglish/live",
  "hostUsername": "aljazeeraenglish",
  "hostUserId": "7074562477175424046",
  "hostDisplayName": "Al Jazeera English",
  "roomId": "7699631452921154317",
  "liveTitle": "Al Jazeera English TikTok LIVE",
  "liveStatus": "2",
  "currentViewers": 22341843,
  "coverUrl": "https://p16-webcast.tiktokcdn-us.com/webcast-oci-tx/7628418490097126158~tplv-obj.image",
  "eventStreamAvailable": false,
  "eventStreamStatus": "Room metadata only; this implementation does not subscribe to LIVE events.",
  "source": "tiktok.com",
  "scrapedAt": "2026-10-25T21:35:23.194Z"
}

The second example is one of the four real offline diagnostic rows from the same run:

{
  "url": "https://www.tiktok.com/@skynews/live",
  "error": "The public LIVE room state indicated the broadcaster was not currently live.",
  "errorCode": "OFFLINE_OR_NO_ROOM_STATE",
  "scrapedAt": "2026-10-25T21:35:22.072Z"
}

Run summary

Run summary is stored separately from the dataset in the run's key-value store under OUTPUT_SUMMARY. It records how many broadcasters were requested, how many room records and diagnostic rows were saved, and which routes were attempted.

Field	Meaning
status	Run outcome: success, partial, blocked, empty, or failed.
source	Source label recorded for the run, tiktok.com.
requestedUsernameCount	Number of usernames supplied in usernames.
requestedLiveUrlCount	Number of URLs supplied in liveUrls.
requestedMaxUsers	Broadcaster limit requested in the input.
requestedTargetCount	Unique broadcasters after combining usernames and URL hosts.
processedUserCount	Broadcasters actually processed after the maxUsers cap.
normalCount	Room records saved.
diagnosticCount	Diagnostic rows saved; set only when includeDiagnostics is enabled.
eventStreamAvailable	Always false; the Actor does not subscribe to LIVE events.
eventStreamStatus	Explicit event-stream limitation.
fixtureMode	Whether a bundled QA fixture was parsed instead of the live route.
readerFallback	Whether a reader fallback was used.
transports	Distinct transports used during the run.
attempts	Array of route attempts with operation, status, size, and outcome.
completedAt	Time the summary was written, in ISO UTC.

Status	Meaning
success	Room records were saved with no diagnostics.
partial	At least one room record was saved, but one or more broadcasters were offline, blocked, or failed. Saved rows remain available.
blocked	No room records were saved because the source returned an access denial or challenge.
empty	No room records were saved because every broadcaster was offline or exposed no public room state.
failed	A request or parse failure occurred before any usable record was saved.

Example OUTPUT_SUMMARY from the 2026-10-25 run:

{
  "status": "partial",
  "source": "tiktok.com",
  "requestedUsernameCount": 5,
  "requestedLiveUrlCount": 0,
  "requestedMaxUsers": 5,
  "requestedTargetCount": 5,
  "processedUserCount": 5,
  "normalCount": 1,
  "diagnosticCount": 4,
  "eventStreamAvailable": false,
  "eventStreamStatus": "Room metadata only; this implementation does not subscribe to LIVE events.",
  "fixtureMode": false,
  "readerFallback": false,
  "transports": [
    "proxy"
  ],
  "attempts": [
    {
      "route": "tiktok_live_public_api",
      "transport": "proxy",
      "statusCode": 200,
      "responseBytes": 20677,
      "contentType": "application/json; charset=utf-8",
      "outcome": "ok"
    },
    {
      "route": "tiktok_live_public_api",
      "transport": "proxy",
      "statusCode": 200,
      "responseBytes": 21648,
      "contentType": "application/json; charset=utf-8",
      "outcome": "ok"
    },
    {
      "route": "tiktok_live_public_api",
      "transport": "proxy",
      "statusCode": 200,
      "responseBytes": 10676,
      "contentType": "application/json; charset=utf-8",
      "outcome": "ok"
    },
    {
      "route": "tiktok_live_public_api",
      "transport": "proxy",
      "statusCode": 200,
      "responseBytes": 114,
      "contentType": "application/json; charset=utf-8",
      "outcome": "ok"
    },
    {
      "route": "tiktok_live_public_api",
      "transport": "proxy",
      "statusCode": 200,
      "responseBytes": 11074,
      "contentType": "application/json; charset=utf-8",
      "outcome": "ok"
    }
  ],
  "completedAt": "2026-10-25T21:35:27.763Z"
}

Coverage and limitations

A room record reflects the public room state at the moment of collection. Viewer counts and live status change continuously, and a broadcaster who is offline produces no room record. An offline or unavailable room is still reported in the dataset when includeDiagnostics is enabled, so an offline state is distinguishable from a blocked request.

The Actor does not capture video or audio, join the room, read chat, gifts, or viewer identities, and does not expose a LIVE event stream; eventStreamAvailable is always false. HTTP errors and access challenges stop that broadcaster without proxy rotation or a different-source fallback. Public usernames must match the host in a supplied LIVE URL, and only canonical https://www.tiktok.com/@name/live URLs are accepted. fixturePath is for offline QA only.

Usage and support

Cost depends on Apify compute, the number of broadcasters, response time, dataset size, and any proxy traffic. Start with one or two usernames, keep maxUsers low, and inspect the room and diagnostic rows before scheduling monitoring runs. See the Actor's Pricing tab for current account rates.

Use the Actor Issues page to report a problem. Include the run ID, the input used, and the run summary; do not include tokens, cookies, or private data. This Actor is not affiliated with, endorsed by, or sponsored by TikTok. Use it only for public data and in accordance with the source's terms, robots guidance, and applicable law. Public pages can contain personal information; use the output only for lawful purposes.