# YouTube Live Stream Scraper (`automation-lab/youtube-live-stream-scraper`) Actor πŸŽ₯ Discover public YouTube live and upcoming streams with channel, timing, thumbnail, viewer, badge, and source metadata. - **URL**: https://apify.com/automation-lab/youtube-live-stream-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ## YouTube Live Stream Scraper Discover public YouTube live and upcoming streams without a YouTube Data API key. Export clean stream, channel, timing, thumbnail, audience-signal, badge, and source metadata to datasets, JSON, CSV, Excel, APIs, or automation tools. Use it for recurring media monitoring, event research, creator intelligence, livestream directories, and brand tracking. ### What does YouTube Live Stream Scraper do? This Actor reads YouTube's public web surfaces and finds stream records embedded in the page's initial data. It supports the YouTube Live discovery page, public search pages, channel pages, watch URLs, and convenient search queries. Each stream is normalized into one stable record and deduplicated by video ID. No Google Cloud project, OAuth flow, YouTube API quota, or private account is required. ### Who is it for? #### Media monitors Run hourly searches for breaking broadcasts, then compare stable `videoId` values with the previous dataset to alert editors only when a new stream appears. #### Event researchers Search for conferences, launches, hearings, or sports coverage, filter upcoming streams, and export schedules and channel links to a planning sheet. #### Brand and creator teams Monitor live mentions, sponsored creator activity, channel ownership, badges, and public audience signals across recurring campaigns. #### Livestream directory operators Combine the YouTube Live page with topic or channel sources, deduplicate records, and refresh a public discovery feed on an Apify schedule. #### Developers and data teams Feed normalized stream records into alerts, dashboards, archives, databases, or enrichment pipelines through the API, webhooks, or MCP. ### Why use this YouTube livestream scraper? YouTube's official API requires setup, credentials, quotas, and API-specific query logic. This Actor provides an Apify-native workflow with schedulable runs and export-ready records. You can start from a broad live page, precise search terms, or specific public URLs. Optional fields fail gracefully when YouTube omits them. Raw badges are preserved so downstream workflows can interpret localized labels. ### What YouTube data can I extract? | Field | Meaning | |---|---| | `videoId` | Stable YouTube video identifier | | `url` | Canonical watch URL | | `title` | Stream title | | `description` | Available description snippet | | `channelId` | Stable channel identifier | | `channelName` | Public channel name | | `channelUrl` | Public channel URL | | `thumbnail` | Best available thumbnail URL | | `status` | `LIVE`, `UPCOMING`, or `UNKNOWN` | | `isLive` | Normalized live-now boolean | | `isUpcoming` | Normalized upcoming boolean | | `scheduledStart` | Scheduled start time when exposed | | `viewCountText` | Raw viewer/view signal | | `viewCount` | Parsed numeric signal when possible | | `badges` | Public status and channel badges | | `sourceUrl` | Page where the record was found | | `scrapedAt` | UTC extraction timestamp | ### How to scrape YouTube live streams 1. Open the Actor input page. 2. Keep `https://www.youtube.com/live` or add your own YouTube URLs. 3. Add search queries such as `space launch live` or `earnings call live`. 4. Choose a maximum number of streams. 5. Enable **Live now only** if upcoming streams are not needed. 6. Click **Start**. 7. Export the dataset or connect it to another service. ### Input ```json { "startUrls": [{ "url": "https://www.youtube.com/live" }], "searchQueries": ["breaking news live"], "maxItems": 100, "liveOnly": false, "language": "en-US" } ```` `startUrls` accepts public YouTube Live, search, channel, and watch URLs. `searchQueries` creates filtered YouTube search URLs automatically. `maxItems` limits unique records across all sources. `liveOnly` excludes records that are not confidently marked live now. `language` controls the preferred response language and localized labels. ### Output example ```json { "videoId": "abc123", "url": "https://www.youtube.com/watch?v=abc123", "title": "Space launch live", "channelId": "UCexample", "channelName": "Example Channel", "channelUrl": "https://www.youtube.com/@example", "thumbnail": "https://i.ytimg.com/vi/abc123/hq720.jpg", "status": "LIVE", "isLive": true, "isUpcoming": false, "viewCountText": "12,345 watching", "viewCount": 12345, "badges": ["Verified"], "sourceUrl": "https://www.youtube.com/live", "scrapedAt": "2026-07-12T12:00:00.000Z" } ``` Fields that YouTube does not expose are omitted rather than guessed. ### How much does it cost to scrape YouTube live streams? The Actor uses pay-per-event pricing: a small run-start charge plus a charge for each saved stream. Apify plan tiers receive automatic volume discounts. You can control spend directly with `maxItems`. Start with 20 records to inspect coverage before scheduling a larger workflow. The final live price is always shown in the Apify Console before a run starts. ### Live and upcoming status YouTube uses several renderer variants and localized status labels. The Actor combines overlay text, badges, timing data, and audience labels into normalized fields. `status: LIVE` means the public page indicated a stream is currently live. `status: UPCOMING` means YouTube exposed scheduling or upcoming indicators. `status: UNKNOWN` preserves useful records when the page does not provide a definitive state. Use `liveOnly: true` for alerting systems that only accept confidently live broadcasts. ### Search tips Use concrete phrases that people place in livestream titles. Good examples include `city council meeting live`, `product launch live`, and `football press conference live`. Add several related queries to improve coverage. Use source URLs when you already know the relevant channel or search page. Keep language consistent with the target market. Schedule repeated runs to observe newly appearing stream IDs. ### Monitoring workflow Run the Actor every 10–30 minutes with the same search inputs. Store or compare `videoId` values in your destination system. Trigger alerts only for IDs not seen in a previous run. Use `channelId` as the durable creator key even when a channel changes its display name. Use `scheduledStart` to build event calendars when YouTube exposes it. Use `viewCount` for rough prioritization while preserving `viewCountText` for auditability. ### Integrations - Send new streams to Slack or Microsoft Teams with Apify integrations. - Append records to Google Sheets for editorial review. - Load datasets into BigQuery, Snowflake, or a data warehouse. - Trigger Make, Zapier, or n8n workflows from completed runs. - Poll the Apify API from a media-monitoring backend. - Export CSV or Excel for one-off research. - Use webhooks to notify a directory when a run finishes. ### API usage with JavaScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/youtube-live-stream-scraper').call({ searchQueries: ['technology conference live'], maxItems: 100, liveOnly: true, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/youtube-live-stream-scraper').call(run_input={ 'searchQueries': ['space launch live'], 'maxItems': 100, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` ### API usage with cURL ```bash curl -X POST \ 'https://api.apify.com/v2/acts/automation-lab~youtube-live-stream-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"searchQueries":["news live"],"maxItems":50}' ``` Fetch dataset items after the run succeeds using its `defaultDatasetId`. ### Use with Apify MCP Connect the Actor through [Apify MCP](https://mcp.apify.com?tools=automation-lab/youtube-live-stream-scraper). Keep your Apify API token in an environment variable rather than committing it. #### Claude Code ```bash claude mcp add --transport http apify \ "https://mcp.apify.com?tools=automation-lab/youtube-live-stream-scraper" \ --header "Authorization: Bearer $APIFY_TOKEN" ``` Run `claude mcp list` afterward to confirm that the `apify` server is connected. #### Claude Desktop, Cursor, or VS Code Add this server to the client's MCP JSON configuration (replace the placeholder locally): ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com?tools=automation-lab/youtube-live-stream-scraper", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` Restart or reload the client, then verify that the YouTube Live Stream Scraper tool appears before sending a prompt. Example prompts: - β€œFind public YouTube streams live now about the space launch.” - β€œExtract upcoming conference streams and group them by channel.” - β€œReturn the newest live news streams as a compact table.” ### Scheduling and change detection Apify schedules can run the same input hourly, daily, or at a custom interval. The Actor itself returns the current public snapshot. For change detection, compare stable `videoId` values between runs. A named dataset, database, sheet, or automation platform can retain prior IDs. Avoid treating changing viewer counts as new streams. ### Data quality and limitations Results reflect public YouTube web data available at run time. YouTube can personalize, localize, reorder, or omit results. Viewer text may represent concurrent viewers or ordinary views depending on the renderer. Numeric parsing understands common K, M, and B suffixes but the raw text remains authoritative. Private, members-only, age-gated, deleted, or region-blocked content may not be available. This Actor does not download video or audio media. ### Legality: is it legal to scrape YouTube live-stream metadata? The Actor collects metadata visible on public web pages. Your use case, jurisdiction, contract, and data-retention choices determine your obligations. Respect applicable laws, YouTube terms, copyright, privacy, and reasonable request rates. Do not use the data for harassment, discrimination, surveillance, or infringement. If uncertain, obtain legal advice for your specific workflow. ### FAQ and troubleshooting **Why did my query return no streams?** Try a broader query, remove `liveOnly`, add `live` to the phrase, or provide a known YouTube search URL. **Why is status UNKNOWN?** YouTube sometimes exposes a video on a live-oriented surface without a definitive live/upcoming marker. The Actor preserves the useful record instead of inventing a status. **Why is scheduledStart missing?** YouTube does not expose a machine-readable schedule on every renderer. **Why do results differ by run?** YouTube discovery ordering changes continuously and may vary by language or region. ### Related scrapers Explore other public data tools from [automation-lab](https://apify.com/automation-lab). Use a YouTube channel scraper when you need complete channel/video catalogs rather than live discovery. Use a YouTube comments scraper when the workflow focuses on audience discussion. Use this Actor when live-now and upcoming discovery is the primary job. ### Support Open an issue from the Actor page with the input, run ID, expected behavior, and a public example URL. Do not include passwords, private cookies, personal tokens, or confidential data. Renderer changes are easiest to diagnose when a reproducible public URL is included. ### Start discovering YouTube livestreams Begin with the prefilled Live page and a low item limit. Review the structured output, then add topic searches and scheduling for your production workflow. The resulting dataset is ready for filtering, export, APIs, alerts, dashboards, and AI analysis. # Actor input Schema ## `startUrls` (type: `array`): Live, search, channel, or watch URLs to inspect. ## `searchQueries` (type: `array`): Find public YouTube live streams matching these terms. ## `maxItems` (type: `integer`): Maximum unique stream records to save. ## `liveOnly` (type: `boolean`): Exclude upcoming and unknown-status videos. ## `language` (type: `string`): Preferred YouTube response language (for example en-US). ## Actor input object example ```json { "startUrls": [ { "url": "https://www.youtube.com/live" } ], "searchQueries": [ "breaking news live" ], "maxItems": 20, "liveOnly": false, "language": "en-US" } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "startUrls": [ { "url": "https://www.youtube.com/live" } ], "searchQueries": [ "breaking news live" ], "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/youtube-live-stream-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 = { "startUrls": [{ "url": "https://www.youtube.com/live" }], "searchQueries": ["breaking news live"], "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/youtube-live-stream-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 '{ "startUrls": [ { "url": "https://www.youtube.com/live" } ], "searchQueries": [ "breaking news live" ], "maxItems": 20 }' | apify call automation-lab/youtube-live-stream-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/youtube-live-stream-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Live Stream Scraper", "description": "πŸŽ₯ Discover public YouTube live and upcoming streams with channel, timing, thumbnail, viewer, badge, and source metadata.", "version": "0.1", "x-build-id": "6DljOeUFMc9SMDUn8" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~youtube-live-stream-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-youtube-live-stream-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/automation-lab~youtube-live-stream-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-youtube-live-stream-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/automation-lab~youtube-live-stream-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-youtube-live-stream-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": { "startUrls": { "title": "πŸŽ₯ YouTube source URLs", "type": "array", "description": "Live, search, channel, or watch URLs to inspect.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Find public YouTube live streams matching these terms.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum streams", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum unique stream records to save.", "default": 100 }, "liveOnly": { "title": "Live now only", "type": "boolean", "description": "Exclude upcoming and unknown-status videos.", "default": false }, "language": { "title": "Language", "type": "string", "description": "Preferred YouTube response language (for example en-US).", "default": "en-US" } } }, "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 } } } } } } } } } } ```