# TikTok LIVE Event Stream Scraper (`crawlerbros/tiktok-live-scraper`) Actor Capture real-time events from TikTok LIVE streams including chat messages, gifts, likes, joins, shares, and viewer stats. Requires the broadcaster to be live at runtime. - **URL**: https://apify.com/crawlerbros/tiktok-live-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Developer tools, Automation - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok LIVE Scraper Capture real-time events from TikTok LIVE streams. Two modes: Mode A (room metadata — no cookie required, always works if the broadcaster is currently live) retrieves roomId, viewerCount, likeCount, title, stream URLs, and host profile in a single dataset row. Mode B (event stream — requires a sessionid cookie) captures timestamped chat messages, gifts, likes, joins, shares, and stats updates as individual rows. The actor exits cleanly with zero rows and no error when the broadcaster is not currently live. ### What this actor does - Monitors one or more TikTok usernames or live URLs for active LIVE sessions - Mode A (no cookie): emits one room-metadata row per live user with title, viewer count, like count, stream URLs, and host profile - Mode B (sessionid cookie): connects to the LIVE event stream and captures every chat message, gift, like, join, share, and stats update as a separate row - Stops cleanly after `connectionDuration` seconds or after `eventCap` events — whichever comes first - Supports an optional `eventTypes` filter to capture only specific event categories - Exits cleanly with zero rows and a log message when a broadcaster is not live — this is correct behavior, not a failure - Empty fields are omitted ### Output per room-metadata row (Mode A) - `roomId` — unique TikTok LIVE room identifier - `username` — broadcaster's TikTok username - `displayName` — broadcaster's display name - `title` — current LIVE stream title - `viewerCount` — current live viewer count - `likeCount` — cumulative like count for the stream - `startTime` — ISO 8601 timestamp when the stream started - `hostUserId` — broadcaster's TikTok user ID - `hostAvatarUrl` — broadcaster's avatar image URL - `streamUrl` — HLS or FLV stream URL (when available) - `status` — stream status string - `scrapedAt` — ISO 8601 timestamp of collection ### Output per event row (Mode B) - `roomId` — unique TikTok LIVE room identifier - `eventType` — event category: `chat`, `gift`, `like`, `join`, `share`, `follow`, `stats`, or `unknown` - `timestamp` — ISO 8601 UTC timestamp when the event was received - `user.id` — sender's TikTok user ID - `user.username` — sender's TikTok username - `user.displayName` — sender's display name - `user.avatarUrl` — sender's avatar image URL - `payload.text` — chat message text (chat events) - `payload.giftId` — gift identifier (gift events) - `payload.count` — gift quantity or like count (gift and like events) ### Input | Field | Type | Default | Description | |---|---|---|---| | `usernames` | array of strings | — | TikTok usernames to monitor for LIVE sessions (without the `@` symbol). | | `liveUrls` | array of strings | — | Direct TikTok LIVE URLs (e.g. `https://www.tiktok.com/@username/live`). Alternative to `usernames`. | | `connectionDuration` | integer | `60` | Seconds to stay connected per stream (10–3600). The actor disconnects cleanly after this window. | | `eventCap` | integer | `500` | Stop collecting events from a stream after this many rows (1–10000). | | `eventTypes` | array of strings | `["all"]` | Filter to specific event types: `chat`, `gift`, `like`, `follow`, `share`, `join`, `stats`, `all`. | | `sessionCookie` | string (secret) | — | Your TikTok `sessionid` cookie value. Required for Mode B (event stream). Without it, the actor runs in Mode A (room metadata only). | #### Example: Mode A — room metadata, no cookie ```json { "usernames": ["natgeo"], "connectionDuration": 10 } ```` #### Example: Mode B — event stream with cookie ```json { "usernames": ["khaby.lame"], "connectionDuration": 120, "eventCap": 1000, "eventTypes": ["chat", "gift", "stats"], "sessionCookie": "your_sessionid_value_here" } ``` #### Example: Monitor multiple accounts simultaneously ```json { "usernames": ["natgeo", "bbcnews", "cnn"], "connectionDuration": 60 } ``` #### Example: Monitor a specific live URL ```json { "liveUrls": ["https://www.tiktok.com/@natgeo/live"], "connectionDuration": 30 } ``` ### Use cases - **Community management** — monitor chat messages and viewer reactions during your own brand's live events in real time - **Influencer research** — capture viewership counts, like velocity, and gift activity for live-streaming creators to gauge audience engagement - **Event coverage** — archive the complete chat and event stream from a product launch, sports event, or music performance broadcast on TikTok - **Competitive analysis** — track how frequently competitor brands go live and compare peak viewer counts over time - **Content moderation** — scan live chat streams for spam, harmful keywords, or policy violations during high-traffic events ### FAQ **Q: What happens if the broadcaster is not live when the actor runs?**\ A: The actor logs a message and exits cleanly with zero dataset rows. This is expected behavior. Schedule the actor during the creator's typical streaming hours for best results. **Q: Does Mode A require a cookie?**\ A: No. Mode A (room metadata) works without any authentication. It retrieves title, viewer count, like count, stream URLs, and host profile for any broadcaster who is currently live. **Q: How do I get my sessionid cookie for Mode B?**\ A: Install the Cookie-Editor browser extension, log into TikTok in your browser, open Cookie-Editor, find the cookie named `sessionid`, and copy its value. Paste it into the `sessionCookie` input field. **Q: Is the sessionid cookie stored or logged?**\ A: No. The cookie is used only to authenticate the WebSocket connection within the actor run and is not persisted or logged anywhere. **Q: What does `connectionDuration` control?**\ A: It sets how many seconds the actor stays connected to each LIVE stream. A 60-second window typically captures hundreds of chat events during an active stream. Increase it to archive longer sessions. **Q: Can I monitor multiple users in one run?**\ A: Yes. Add multiple usernames to the `usernames` array. The actor processes each one sequentially — connecting, collecting events for `connectionDuration` seconds, then moving to the next. **Q: What is the `unknown` event type?**\ A: TikTok sends some event types not yet mapped to a named category. The actor preserves the raw frame method name and payload size as `rawMethod` and `payloadSize` for debugging purposes. **Q: What stream formats does Mode A return in `streamUrl`?**\ A: When available, the actor captures HLS (m3u8) and FLV stream URLs at resolutions including 360p, 720p, 720p60, and 1080p60. ### Related TikTok Scrapers Build a complete TikTok data pipeline with our full suite: | Scraper | URL | |---|---| | TikTok Post Scraper | https://apify.com/crawlerbros/tiktok-post-scraper | | TikTok Profile Scraper | https://apify.com/crawlerbros/tiktok-profile-scraper | | TikTok Comments Scraper | https://apify.com/crawlerbros/tiktok-comments-scraper | | TikTok Search Scraper | https://apify.com/crawlerbros/tiktok-search-scraper | | TikTok Hashtag Scraper | https://apify.com/crawlerbros/tiktok-hashtag-scraper | | TikTok Music Scraper | https://apify.com/crawlerbros/tiktok-music-scraper | | TikTok Transcript Scraper | https://apify.com/crawlerbros/tiktok-transcript-scraper | | TikTok Followers Scraper | https://apify.com/crawlerbros/tiktok-followers-scraper | | TikTok Mention Scraper | https://apify.com/crawlerbros/tiktok-mention-scraper | | TikTok Profile Mention Scraper | https://apify.com/crawlerbros/tiktok-profile-mention-scraper | | TikTok Playlist Scraper | https://apify.com/crawlerbros/tiktok-playlist-scraper | | TikTok Explore Scraper | https://apify.com/crawlerbros/tiktok-explore-scraper | | TikTok For You Scraper | https://apify.com/crawlerbros/tiktok-for-you-scraper | | TikTok Downloader | https://apify.com/crawlerbros/tiktok-downloader-api | | TikTok Ads Library Scraper | https://apify.com/crawlerbros/tiktok-ads-library-scraper-pro | | TikTok Top Ads Scraper | https://apify.com/crawlerbros/tiktok-top-ads-scraper | | TikTok Hashtag Trends Scraper | https://apify.com/crawlerbros/tiktok-hashtag-trends-scraper | # Actor input Schema ## `usernames` (type: `array`): 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` (type: `array`): Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames. ## `connectionDuration` (type: `integer`): How long to stay connected to each LIVE stream and collect events. ## `eventCap` (type: `integer`): Stop collecting events from a stream after capturing this many. Applies per stream. ## `eventTypes` (type: `array`): Which event types to capture and push to the dataset. Use 'all' to capture every event type. ## `sessionCookie` (type: `string`): 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. ## Actor input object example ```json { "usernames": [ "natgeo" ], "connectionDuration": 10, "eventCap": 100, "eventTypes": [ "all" ] } ``` # Actor output Schema ## `events` (type: `string`): Dataset containing all captured LIVE stream events. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "usernames": [ "natgeo" ], "connectionDuration": 10, "eventCap": 100, "eventTypes": [ "all" ] }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/tiktok-live-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "usernames": ["natgeo"], "connectionDuration": 10, "eventCap": 100, "eventTypes": ["all"], } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/tiktok-live-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "usernames": [ "natgeo" ], "connectionDuration": 10, "eventCap": 100, "eventTypes": [ "all" ] }' | apify call crawlerbros/tiktok-live-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tiktok-live-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok LIVE Event Stream Scraper", "description": "Capture real-time events from TikTok LIVE streams including chat messages, gifts, likes, joins, shares, and viewer stats. Requires the broadcaster to be live at runtime.", "version": "1.0", "x-build-id": "J7Zc4Cy8lU9HX9ggi" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tiktok-live-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tiktok-live-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~tiktok-live-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-tiktok-live-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~tiktok-live-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tiktok-live-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "usernames": { "title": "Usernames", "type": "array", "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.", "items": { "type": "string" } }, "liveUrls": { "title": "Live Stream URLs", "type": "array", "description": "Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames.", "items": { "type": "string" } }, "connectionDuration": { "title": "Connection Duration (Seconds)", "minimum": 10, "maximum": 3600, "type": "integer", "description": "How long to stay connected to each LIVE stream and collect events.", "default": 60 }, "eventCap": { "title": "Event Cap", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop collecting events from a stream after capturing this many. Applies per stream.", "default": 500 }, "eventTypes": { "title": "Event Type Filter", "type": "array", "description": "Which event types to capture and push to the dataset. Use 'all' to capture every event type.", "items": { "type": "string", "enum": [ "chat", "gift", "like", "follow", "share", "join", "stats", "all" ] }, "default": [ "all" ] }, "sessionCookie": { "title": "Session Cookie (sessionid) — for event-stream mode", "type": "string", "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." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```