{ "openapi": "3.0.1", "info": { "title": "Youtube Live Chat Scraper", "description": "YouTube Live Chat Scraper extracts live chat from YouTube live streams and replays. Supports full replay chat (most reliable) and best-effort live polling. Outputs messages with timestamps, authors, badges (owner/mod/member), Super Chats/Stickers, and stream metadata for analytics and AI.", "version": "1.1", "x-build-id": "Ns7luAcWTxyrvN1WN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/coregent~youtube-live-chat-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-coregent-youtube-live-chat-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/coregent~youtube-live-chat-scraper/runs": { "post": { "operationId": "runs-sync-coregent-youtube-live-chat-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/coregent~youtube-live-chat-scraper/run-sync": { "post": { "operationId": "run-sync-coregent-youtube-live-chat-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": { "mode": { "title": "Extraction mode", "enum": [ "replay", "live" ], "type": "string", "description": "**Pick one per run.**\n\n- **Replay (recommended)** ā€” extracts the *complete* chat of a stream that has already ended, from the first message to the last. This is the reliable mode, and the one the official YouTube API cannot do at all.\n- **Live** ā€” polls an *currently airing* stream and captures messages as they arrive. Best-effort: you only get what is posted while the run is active.\n\nšŸ’” **TIP:** if a stream has ended, use Replay. Live mode on an ended stream returns nothing.", "default": "replay" }, "videoRefs": { "title": "Video URLs or IDs", "type": "array", "description": "YouTube live streams or replays to extract chat from.\n\nAccepts either form, mixed freely in one list:\n- Full watch URL: `https://www.youtube.com/watch?v=BZ_UzbpMjMg`\n- Short URL: `https://youtu.be/BZ_UzbpMjMg`\n- Bare 11-character video ID: `BZ_UzbpMjMg`\n\nšŸ’” **TIP:** the video must have had live chat, and chat replay must still be enabled on it. Ordinary uploads have no chat to extract. Leave this empty if you are using Channel Discovery below instead.", "items": { "type": "string" }, "default": [] }, "channelRefs": { "title": "Channel URLs or handles", "type": "array", "description": "**Channel discovery only.** Provide channels and the Actor finds their streams for you ā€” no need to know the video IDs.\n\nAccepts any of:\n- Handle: `@LofiGirl`\n- Handle URL: `https://www.youtube.com/@LofiGirl`\n- Canonical channel ID: `UCSJ4gkVC6NrvII8umztf0Ow`\n- Channel URL: `https://www.youtube.com/channel/UCSJ4gkVC6NrvII8umztf0Ow`\n\nšŸ’” **TIP:** this is the fastest way to monitor a creator ā€” paste the handle and let the Actor find every recent stream. Combine with the discovery controls below to narrow what it picks up.", "items": { "type": "string" }, "default": [] }, "channelDiscoveryMode": { "title": "Which streams to discover", "enum": [ "current_live_then_replays", "current_live_only", "latest_replays_only" ], "type": "string", "description": "**Channel discovery only.** Controls what the Actor looks for on each channel.\n\n- **Live then replays** ā€” currently-airing streams first, then recent finished ones. Good default.\n- **Current live only** ā€” only streams airing right now. Returns nothing if the channel is not live.\n- **Latest replays only** ā€” only finished streams. Best for analytics and back-catalogue work.", "default": "current_live_then_replays" }, "maxVideosPerChannel": { "title": "Max videos per channel", "minimum": 1, "maximum": 50, "type": "integer", "description": "**Channel discovery only.** How many streams to take from each channel.\n\nāš ļø **This multiplies your results and your bill.** 5 channels Ɨ 10 videos Ɨ 5,000 messages = 250,000 rows. Set *Max total chat events* below to put a hard ceiling on any run.", "default": 5 }, "lookbackDays": { "title": "Only replays from the last N days", "minimum": 0, "maximum": 365, "type": "integer", "description": "**Channel discovery only.** Ignore replays older than this many days. Set to `0` for no age limit.\n\nExample: `7` returns only streams from the past week.", "default": 30 }, "includeUpcomingLives": { "title": "Include scheduled/upcoming streams", "type": "boolean", "description": "**Channel discovery only.** Include streams that are scheduled but have not started.\n\nšŸ’” Usually leave off ā€” a stream that has not aired has no chat yet, so these produce empty results.", "default": false }, "includeMembersOnly": { "title": "Include members-only streams", "type": "boolean", "description": "**Channel discovery only.** Include streams restricted to channel members.\n\nšŸ’” Usually leave off ā€” members-only chat sits behind a login this Actor does not have, so extraction is best-effort at most.", "default": false }, "maxMessagesPerVideo": { "title": "Max messages per video", "minimum": 0, "maximum": 200000, "type": "integer", "description": "Stop after this many chat events **from each video**. Set to `0` to capture the entire chat replay however long it is.\n\nA busy multi-hour stream can carry tens of thousands of messages, so the default caps each video at 5,000. When a cap is hit the run stops cleanly and keeps everything collected so far ā€” the log tells you it was truncated.", "default": 5000 }, "maxTotalItems": { "title": "Max total chat events (whole run)", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "**Hard ceiling across every video and channel in the run.** The Actor stops as soon as this many chat events have been collected, and keeps what it has.\n\nSet to `0` for no run-level limit.\n\nšŸ’” **TIP:** this is the single most useful field for controlling spend. *Max messages per video* caps each video individually ā€” with 20 discovered videos that is still 20 Ɨ the per-video cap. This field caps the total.", "default": 0 }, "maxTimePerVideoSecs": { "title": "Max time per video (seconds)", "minimum": 30, "maximum": 7200, "type": "integer", "description": "Give up on a single video after this many seconds and move to the next one. Protects a run from stalling on one very long stream.\n\nExample: `300` = spend at most 5 minutes per video.", "default": 600 }, "includeNormalMessages": { "title": "Include normal chat messages", "type": "boolean", "description": "Include ordinary text messages from viewers ā€” usually the vast bulk of any chat.\n\nšŸ’” **TIP:** turn this **off** to get a monetization-only export. With this off and Super Chats on, a 50,000-message stream returns just the few hundred paid events, and you are only charged for those.", "default": true }, "includeSuperChats": { "title": "Include Super Chats & Super Stickers", "type": "boolean", "description": "Include paid messages, with the amount, currency and tier colour of each.\n\nUse this for revenue tracking ā€” who paid, how much, and what they said.", "default": true }, "includeMembershipEvents": { "title": "Include membership events", "type": "boolean", "description": "Include channel membership joins, renewals and gifted memberships shown in chat, with the membership tier where YouTube exposes it.", "default": true }, "includeModerationEvents": { "title": "Include moderation & system events", "type": "boolean", "description": "Include deleted messages, banned users, auto-moderation actions and YouTube's own system notices.\n\nUse this to audit how a chat was moderated ā€” no other field surfaces this.", "default": true }, "liveCaptureDurationSecs": { "title": "How long to capture (seconds)", "minimum": 10, "maximum": 86400, "type": "integer", "description": "**Live mode only.** Total time to sit on the stream collecting messages. Ignored in Replay mode.\n\nExample: `300` = watch for 5 minutes, `3600` = watch for an hour.\n\nāš ļø A long capture on a quiet stream can run a long time and return very few messages.", "default": 300 }, "stopWhenStreamEnds": { "title": "Stop when the stream ends", "type": "boolean", "description": "**Live mode only.** Finish the run as soon as the stream goes offline, instead of waiting out the full capture duration. Recommended.", "default": true }, "maxConcurrency": { "title": "Videos processed in parallel", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many videos to work on at once. Higher is faster on large batches; lower is gentler and less likely to be rate-limited.\n\nšŸ’” Leave at 3 unless you are processing many videos and want more speed.", "default": 3 }, "pollIntervalMs": { "title": "Live poll interval (ms)", "minimum": 2000, "maximum": 10000, "type": "integer", "description": "**Live mode only.** How often to check for new messages, in milliseconds. Lower means fresher data but many more requests for no extra results.\n\nšŸ’” Leave at 2000 (2 seconds) unless you have a specific reason.", "default": 2000 }, "language": { "title": "Language", "enum": [ "en", "es", "fr", "de", "ja", "ko", "pt", "hi", "zh", "ar" ], "type": "string", "description": "Language YouTube should use for localized text such as system messages (the `hl` parameter). Does not translate viewers' messages.", "default": "en" }, "regionCode": { "title": "Region", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "JP", "BR", "MX", "KR", "ES" ], "type": "string", "description": "Country YouTube should treat the request as coming from (the `gl` parameter). Affects localized formatting such as Super Chat currency display.", "default": "US" }, "useProxy": { "title": "Use Apify residential proxy", "type": "boolean", "description": "Route requests through Apify's residential proxy.\n\nšŸ’” **Leave this off unless a run is actually being blocked.** This Actor is HTTP-only and runs reliably without a proxy ā€” enabling one adds no speed and can slow a run down.", "default": false }, "proxyCountryCode": { "title": "Proxy exit country", "enum": [ "", "US", "GB", "CA", "AU", "IN", "DE", "FR", "JP", "BR", "MX" ], "type": "string", "description": "Pin proxy traffic to one country. Only applies when *Use Apify residential proxy* is on. Leave blank to let Apify choose.", "default": "" }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 10, "maximum": 120, "type": "integer", "description": "How long to wait for a single HTTP request before treating it as failed.", "default": 30 }, "maxRetries": { "title": "Max retries", "minimum": 0, "maximum": 10, "type": "integer", "description": "How many times to retry a request that fails with a rate-limit (429) or server (5xx) error, using exponential backoff.", "default": 3 }, "minDelayMs": { "title": "Minimum delay between requests (ms)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Pause at least this long between chat page requests. Raise it if you see rate limiting on very large runs.", "default": 0 } } }, "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 } } } } } } } } } }