TikTok LIVE Room Status & Chat Capture Tool

Check TikTok usernames for an active LIVE stream and get room title, viewer counts, and host profile, or capture real-time chat, gifts, likes, and other events while the stream runs.

Open on Apify GitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

Field	Type	Required	Description
`usernames`	array	optional	TikTok usernames to watch for LIVE streams (without the @ symbol). The actor will check each username for an active LIVE session. Note: the prefill account may not always be live — runs during off-hours may produce 0 rows. This is expected behavior.
`liveUrls`	array	optional	Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames.
`connectionDuration`	integer	optional	How long to stay connected to each LIVE stream and collect events.

Show all input fields

Field	Type	Required	Description
`usernames`	array	optional	TikTok usernames to watch for LIVE streams (without the @ symbol). The actor will check each username for an active LIVE session. Note: the prefill account may not always be live — runs during off-hours may produce 0 rows. This is expected behavior.
`liveUrls`	array	optional	Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames.
`connectionDuration`	integer	optional	How long to stay connected to each LIVE stream and collect events.
`eventCap`	integer	optional	Stop collecting events from a stream after capturing this many. Applies per stream.
`eventTypes`	array	optional	Which event types to capture and push to the dataset. Use 'all' to capture every event type.
`sessionCookie`	string	optional	Optional. Value of the TikTok `sessionid` cookie from a logged-in browser session. When provided, the actor captures real-time events (chat, gifts, likes, follows, joins) from the LIVE stream. Without this, the actor runs in room-metadata mode (1 row per live user: title, viewer count, stream URLs, host profile). To obtain: open TikTok in a browser → DevTools → Application → Cookies → copy the `sessionid` value.

Download the published input schema

View complete JSON

{
  "description": "Monitor TikTok LIVE streams. Without a sessionCookie: emits one room-metadata row per live user (title, viewer count, stream URLs, host stats). With a sessionCookie: captures real-time events (chat, gifts, likes, follows, joins).",
  "properties": {
    "connectionDuration": {
      "default": 60,
      "description": "How long to stay connected to each LIVE stream and collect events.",
      "maximum": 3600,
      "minimum": 10,
      "prefill": 10,
      "title": "Connection Duration (Seconds)",
      "type": "integer"
    },
    "eventCap": {
      "default": 500,
      "description": "Stop collecting events from a stream after capturing this many. Applies per stream.",
      "maximum": 10000,
      "minimum": 1,
      "prefill": 100,
      "title": "Event Cap",
      "type": "integer"
    },
    "eventTypes": {
      "default": [
        "all"
      ],
      "description": "Which event types to capture and push to the dataset. Use 'all' to capture every event type.",
      "editor": "select",
      "items": {
        "enum": [
          "chat",
          "gift",
          "like",
          "follow",
          "share",
          "join",
          "stats",
          "all"
        ],
        "type": "string"
      },
      "prefill": [
        "all"
      ],
      "title": "Event Type Filter",
      "type": "array"
    },
    "liveUrls": {
      "description": "Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "title": "Live Stream URLs",
      "type": "array"
    },
    "sessionCookie": {
      "description": "Optional. Value of the TikTok `sessionid` cookie from a logged-in browser session. When provided, the actor captures real-time events (chat, gifts, likes, follows, joins) from the LIVE stream. Without this, the actor runs in room-metadata mode (1 row per live user: title, viewer count, stream URLs, host profile). To obtain: open TikTok in a browser → DevTools → Application → Cookies → copy the `sessionid` value.",
      "editor": "textfield",
      "isSecret": true,
      "title": "Session Cookie (sessionid) — for event-stream mode",
      "type": "string"
    },
    "usernames": {
      "description": "TikTok usernames to watch for LIVE streams (without the @ symbol). The actor will check each username for an active LIVE session. Note: the prefill account may not always be live — runs during off-hours may produce 0 rows. This is expected behavior.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "prefill": [
        "natgeo"
      ],
      "title": "Usernames",
      "type": "array"
    }
  },
  "required": [],
  "schemaVersion": 1,
  "title": "TikTok LIVE Scraper Input",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

Field	Type	Required	Description
`events`	string	optional	Dataset containing all captured LIVE stream events.

Download the published output schema

View complete JSON

{
  "actorOutputSchemaVersion": 1,
  "description": "TikTok LIVE room-status records (title, viewer counts, host profile) or captured LIVE event records (chat, gifts, likes, joins, shares, stats).",
  "properties": {
    "events": {
      "description": "Dataset containing all captured LIVE stream events.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "TikTok LIVE events",
      "type": "string"
    }
  },
  "title": "TikTok LIVE Room Status & Chat Capture Tool Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON

{
  "actorSpecification": 1,
  "fields": {
    "currentViewers": {
      "description": "Concurrent viewers at time of scrape (room-metadata mode only)",
      "title": "Current Viewers",
      "type": "integer"
    },
    "eventTimestamp": {
      "description": "ISO 8601 UTC datetime from TikTok's event createTime (event-stream mode, when available)",
      "title": "Event Timestamp",
      "type": "string"
    },
    "eventType": {
      "description": "Event type for event-stream mode: 'chat', 'gift', 'like', 'follow', 'share', 'join', 'stats', or 'other'",
      "title": "Event Type",
      "type": "string"
    },
    "hostAvatarUrl": {
      "description": "URL of the streamer's avatar image (room-metadata mode only)",
      "title": "Host Avatar URL",
      "type": "string"
    },
    "hostBio": {
      "description": "Streamer bio/signature (room-metadata mode only)",
      "title": "Host Bio",
      "type": "string"
    },
    "hostDisplayName": {
      "description": "Display name of the streamer (room-metadata mode only)",
      "title": "Host Display Name",
      "type": "string"
    },
    "hostFollowerCount": {
      "description": "Number of followers the streamer has (room-metadata mode only)",
      "title": "Host Follower Count",
      "type": "integer"
    },
    "hostFollowingCount": {
      "description": "Number of accounts the streamer follows (room-metadata mode only)",
      "title": "Host Following Count",
      "type": "integer"
    },
    "hostUserId": {
      "description": "TikTok user ID of the streamer (room-metadata mode only)",
      "title": "Host User ID",
      "type": "string"
    },
    "hostUsername": {
      "description": "Username of the streamer (room-metadata mode only)",
      "title": "Host Username",
      "type": "string"
    },
    "hostVerified": {
      "description": "Whether the streamer has a verified badge (room-metadata mode only)",
      "title": "Host Verified",
      "type": "boolean"
    },
    "liveRoomMode": {
      "description": "TikTok internal room mode code (room-metadata mode only)",
      "title": "Live Room Mode",
      "type": "integer"
    },
    "liveStatus": {
      "description": "TikTok internal status code for the LIVE room (4 = active)",
      "title": "Live Status",
      "type": "integer"
    },
    "liveTitle": {
      "description": "Title of the LIVE stream (room-metadata mode only)",
      "title": "Live Title",
      "type": "string"
    },
    "liveUrl": {
      "description": "URL to the LIVE stream page (room-metadata mode only)",
      "title": "Live URL",
      "type": "string"
    },
    "msgId": {
      "description": "TikTok internal message ID for deduplication (event-stream mode, when available)",
      "title": "Message ID",
      "type": "string"
    },
    "payload": {
      "description": "Event-type-specific data: text (chat), giftName/giftId/giftCount (gift), totalLikes (like), viewerCount/totalUsers (stats)",
      "properties": {
        "actionId": {
          "title": "Action ID",
          "type": "integer"
        },
        "giftCount": {
          "title": "Gift Count",
          "type": "integer"
        },
        "giftId": {
          "title": "Gift ID",
          "type": "string"
        },
        "giftName": {
          "title": "Gift Name",
          "type": "string"
        },
        "payloadSize": {
          "title": "Payload Size",
          "type": "integer"
        },
        "rawMethod": {
          "title": "Raw Method",
          "type": "string"
        },
        "text": {
          "title": "Chat Text",
          "type": "string"
        },
        "totalLikes": {
          "title": "Total Likes",
          "type": "integer"
        },
        "totalUsers": {
          "title": "Total Users",
          "type": "integer"
        },
        "viewerCount": {
          "title": "Viewer Count",
          "type": "integer"
        }
      },
      "title": "Payload",
      "type": "object"
    },
    "receivedAt": {
      "description": "ISO 8601 UTC datetime when the event was captured (event-stream mode)",
      "title": "Received At",
      "type": "string"
    },
    "roomId": {
      "description": "TikTok LIVE room ID (string to preserve 64-bit precision)",
      "title": "Room ID",
      "type": "string"
    },
    "scrapedAt": {
      "description": "ISO 8601 UTC timestamp when the data was collected",
      "title": "Scraped At",
      "type": "string"
    },
    "startTime": {
      "description": "Stream start time as a Unix timestamp (room-metadata mode only)",
      "title": "Start Time (Unix)",
      "type": "integer"
    },
    "startedAt": {
      "description": "Stream start time in ISO 8601 UTC format (room-metadata mode only)",
      "title": "Started At",
      "type": "string"
    },
    "streamUrls": {
      "description": "HLS and FLV playback URLs at multiple qualities (hls_ld, hls_sd, hls_hd, hls_hd_60, hls_uhd_60, flv_ld, flv_sd, flv_hd, etc.) — room-metadata mode only",
      "title": "Stream URLs",
      "type": "object"
    },
    "totalViewers": {
      "description": "Cumulative unique viewers since stream started (room-metadata mode only)",
      "title": "Total Viewers",
      "type": "integer"
    },
    "user": {
      "description": "User who triggered the event (event-stream mode; absent for 'stats' and 'other' events)",
      "properties": {
        "avatarUrl": {
          "title": "Avatar URL",
          "type": "string"
        },
        "displayName": {
          "title": "Display Name",
          "type": "string"
        },
        "id": {
          "title": "User ID",
          "type": "string"
        },
        "username": {
          "title": "Username",
          "type": "string"
        }
      },
      "title": "User",
      "type": "object"
    }
  },
  "title": "TikTok LIVE Data",
  "views": {
    "overview": {
      "description": "Room metadata rows (no sessionCookie) or real-time event rows (with sessionCookie). Room-metadata rows include stream URLs, viewer counts, and host profile. Event rows include chat messages, gifts, likes, joins, and viewer stats.",
      "display": {
        "component": "table",
        "properties": {
          "eventType": {
            "format": "text",
            "label": "Event Type"
          },
          "hostUsername": {
            "format": "text",
            "label": "Host"
          },
          "liveTitle": {
            "format": "text",
            "label": "Title"
          },
          "payload": {
            "format": "text",
            "label": "Payload"
          },
          "receivedAt": {
            "format": "text",
            "label": "Received At"
          },
          "roomId": {
            "format": "text",
            "label": "Room ID"
          },
          "totalViewers": {
            "format": "number",
            "label": "Total Viewers"
          },
          "user": {
            "format": "text",
            "label": "User"
          }
        }
      },
      "title": "LIVE Data Overview",
      "transformation": {
        "fields": [
          "roomId",
          "hostUsername",
          "liveTitle",
          "totalViewers",
          "eventType",
          "receivedAt",
          "user",
          "payload"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

TikTok LIVE Room Status & Chat Capture Tool

Check whether a TikTok creator is currently LIVE and pull the room's title, viewer counts, and host profile — no login needed. Optionally, with a TikTok session cookie, stay connected to the stream and capture its chat messages, gifts, likes, and other events as they happen.

What this actor does

Checks usernames or LIVE URLs for an active broadcast
Room-status mode (no cookie): one record per live user with title, viewer counts, stream URLs, and host profile
Event-capture mode (session cookie): stays connected and records every chat message, gift, like, join, share, and viewer-stats update as its own record
Time and count limits: stops after connectionDuration seconds or eventCap events, whichever comes first
Event-type filter: capture only the event categories you care about — unmapped (other) events always pass through regardless of the filter, since they can't be matched to a selected category
Exits cleanly with zero records when nobody is live — that's expected behavior, not an error, and empty fields are always omitted

Output per room-status record

roomId — TikTok's LIVE room identifier
hostUsername — broadcaster's TikTok username
hostUserId — broadcaster's TikTok user ID
hostDisplayName — broadcaster's display name
hostVerified — whether the host's account is verified
hostBio — the host's profile bio text
hostAvatarUrl — host's avatar image URL
hostFollowerCount, hostFollowingCount — the host's follower and following counts
liveTitle — the current LIVE stream's title
liveStatus, liveRoomMode — TikTok's room status and mode values
startTime, startedAt — when the stream started, as a raw timestamp and as an ISO 8601 string
totalViewers — cumulative viewer count since the stream started
currentViewers — current live viewer count
liveUrl — the broadcaster's LIVE URL
streamUrls — a map of stream quality labels (e.g. hls_720p, flv_1080p60) to their playback URLs, when TikTok exposes them
scrapedAt — when the record was fetched

Output per captured event record

roomId — the LIVE room the event came from
eventType — chat, gift, like, follow, share, join, stats, other, or raw
receivedAt — ISO 8601 UTC timestamp when the event arrived
user — object with id, username, displayName, avatarUrl for the user tied to the event, when TikTok includes one
payload — event-specific details:
- chat: text, and emotes when the message includes them
- gift: giftName, giftId, giftCount
- like: totalLikes
- stats: viewerCount, totalUsers
- other (unmapped event types): rawMethod and payloadSize for reference
- raw (undecodable WebSocket frames): rawBase64 and frameSize
- follow/share/join events carry only the user object, with no extra payload

Input

Field	Type	Default	Description
`usernames`	array	–	TikTok usernames to check for an active LIVE session (without `@`)
`liveUrls`	array	–	Direct TikTok LIVE URLs, an alternative to `usernames`
`connectionDuration`	integer	`60`	Seconds to stay connected to each LIVE stream (10–3600)
`eventCap`	integer	`500`	Stop capturing events from a stream after this many (1–10,000), per stream
`eventTypes`	array	`["all"]`	Which event categories to keep: `chat`, `gift`, `like`, `follow`, `share`, `join`, `stats`, or `all`
`sessionCookie`	string	–	TikTok `sessionid` cookie value. Without it, the actor only returns room-status records

{ "usernames": ["natgeo"], "connectionDuration": 10 }

{
  "usernames": ["khaby.lame"],
  "connectionDuration": 120,
  "eventCap": 1000,
  "eventTypes": ["chat", "gift", "stats"],
  "sessionCookie": "your_sessionid_value_here"
}

Example: check several accounts at once

{ "usernames": ["natgeo", "bbcnews", "cnn"], "connectionDuration": 60 }

Example: check a specific LIVE URL

{ "liveUrls": ["https://www.tiktok.com/@natgeo/live"], "connectionDuration": 30 }

Use cases

Live status alerts — check a watchlist of creators and know within seconds who's currently live
Community management — follow your own brand's chat in real time during a live event
Audience research — capture viewer counts and gift activity to gauge how a stream performed
Event archiving — record the chat and event timeline from a launch or performance streamed on TikTok LIVE
Moderation review — pull a stream's chat for later review of comments or reported behavior

FAQ

Is this affiliated with TikTok? No. This is an independent, third-party actor that reads TikTok's publicly available LIVE room data and is not affiliated with or endorsed by TikTok.

What happens if the account isn't live when the actor runs? The actor returns zero records and logs that the creator wasn't live — this is expected, not a failure. Run it during the creator's usual streaming hours for the best chance of a hit.

Do I need a cookie for room-status mode? No. Checking whether someone is live and getting the room's title, viewer counts, and host profile works without any login.

How do I get a session cookie for event-capture mode? Log into TikTok in a browser, open its developer tools, find the cookie named sessionid under Application/Storage, and paste its value into sessionCookie.

Is my session cookie stored anywhere? No. It's used only to connect to the LIVE stream during the run and isn't saved or logged.

What does connectionDuration actually limit? How long the actor stays connected to each stream before moving on. A short window (10–60 seconds) is enough to confirm live status; a longer one is needed to capture a meaningful chat/event history.

Can I check multiple accounts in one run? Yes — list several usernames, and the actor checks each one in turn, connecting and collecting for connectionDuration seconds before moving to the next.

What are the other and raw event types? Some TikTok LIVE message types aren't mapped to a named category — those are kept as other events with rawMethod and payloadSize in the payload, and they're always captured regardless of your eventTypes filter. Occasionally a WebSocket frame can't be decoded at all; when that happens and eventTypes includes all (the default), it's kept as a raw event with the frame's base64 bytes and size, so nothing is silently dropped.

What quality options appear in streamUrls? Whatever TikTok exposes for that stream at the time — typically a mix of HLS and FLV links across resolutions such as 360p, 720p, and 1080p60, when the room is actively broadcasting.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build iiC9O1whFFD37TDyD. Documentation is regenerated from the default published build; private drafts are not included.

TikTok LIVE Room Status & Chat Capture Tool

Input schema

Output schema

Dataset schema

Key-value schema

Published README

TikTok LIVE Room Status & Chat Capture Tool

What this actor does

Output per room-status record

Output per captured event record

Input

Example: check room status, no cookie

Example: capture events with a session cookie

Example: check several accounts at once

Example: check a specific LIVE URL

Use cases

FAQ

Python quickstart