# Youtube Scraper (`lisbuenas/youtube-scraper`) Actor YouTube Scraper extracts bulk public data beyond official API limits. Grab video metadata, view counts, comments, and live like counters from channels, playlists, streams, and search results. Export to JSON, CSV, or Excel via API endpoints, webhooks, or our Python & Node.js SDKs. - **URL**: https://apify.com/lisbuenas/youtube-scraper.md - **Developed by:** [Felipe Lisboa](https://apify.com/lisbuenas) (community) - **Categories:** Videos, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 Scraper Turn YouTube into clean, analysis-ready data in minutes. This Apify Actor extracts public data from YouTube videos, channels, playlists, and search results, with optional subtitle capture for deeper content analysis. ### Features - Start fast: scrape by **URL** (video, channel, playlist, search page) or by **search term** - Stay in control: set independent limits for regular videos, Shorts, and live streams - Refine channel results: filter by date range and sort by Newest, Popular, or Oldest - Narrow search intent: apply sorting and upload-date filters to target the right content - Go deeper with subtitles: download tracks as SRT, WEBVTT, XML, or plain text, and optionally persist to key-value store - Debug with confidence: errors are pushed as explicit dataset items (via the `error` field), never hidden failures ### Input ```json { "startUrls": [ { "url": "https://www.youtube.com/@LofiGirl" }, { "url": "https://www.youtube.com/watch?v=CW7gfrTlr0Y" } ], "searchQueries": ["lofi hip hop"], "maxResults": 10, "maxResultsShorts": 10, "maxResultStreams": 10, "sortingOrder": "relevance", "dateFilter": "week", "oldestPostDate": "2 months", "sortVideosBy": "NEWEST", "downloadSubtitles": false, "saveSubsToKVS": false, "subtitlesLanguage": "en", "subtitlesFormat": "srt", "preferAutoGeneratedSubtitles": false } ```` | Field | Type | Default | Description | |-------|------|---------|-------------| | `startUrls` | array | — | YouTube URLs (video, channel, playlist or search page) | | `searchQueries` | array | — | Search keywords as typed in the YouTube search bar | | `maxResults` | integer | 10 | Max regular videos per URL/query (0 to exclude) | | `maxResultsShorts` | integer | 10 | Max Shorts per search term (0 to exclude) | | `maxResultStreams` | integer | 10 | Max live streams per search term (0 to exclude) | | `sortingOrder` | string | `relevance` | Search result order: `relevance`, `upload_date`, `view_count`, `rating` | | `dateFilter` | string | — | Limit search to: `hour`, `today`, `week`, `month`, `year` | | `oldestPostDate` | string | — | Channel date range, e.g. `2024-01-31` or `2 weeks` | | `sortVideosBy` | string | `NEWEST` | Channel tab sort: `NEWEST`, `POPULAR`, `OLDEST` | | `downloadSubtitles` | boolean | false | Attach subtitles to each video item | | `saveSubsToKVS` | boolean | false | Also save subtitle files to the key-value store | | `subtitlesLanguage` | string | `any` | Preferred language code (e.g. `en`, `es`, `pt`) | | `subtitlesFormat` | string | `srt` | `srt`, `vtt`, `xml`, or `plaintext` | | `preferAutoGeneratedSubtitles` | boolean | false | Prefer auto-generated over user-created tracks | ### Output #### Video item ```json { "title": "Stromae - Santé (Live From The Tonight Show Starring Jimmy Fallon)", "id": "CW7gfrTlr0Y", "url": "https://www.youtube.com/watch?v=CW7gfrTlr0Y", "thumbnailUrl": "https://i.ytimg.com/vi/CW7gfrTlr0Y/maxresdefault.jpg", "viewCount": 35582192, "date": "2021-12-21", "likes": 512238, "location": null, "channelName": "StromaeVEVO", "channelUrl": "https://www.youtube.com/@StromaeVEVO", "numberOfSubscribers": 6930000, "duration": "00:03:17", "commentsCount": 14, "text": "...", "descriptionLinks": [], "hashtags": [], "subtitles": null, "comments": null, "isMonetized": true, "commentsTurnedOff": false } ``` #### Channel item ```json { "id": "HV6OlMPn5sI", "title": "Raimu - The Spirit Within 🍃 [lofi hip hop/relaxing beats]", "duration": "29:54", "channelName": "Lofi Girl", "channelUrl": "https://www.youtube.com/channel/UCSJ4gkVC6NrvII8umztf0Ow", "date": "10 months ago", "url": "https://www.youtube.com/watch?v=HV6OlMPn5sI", "viewCount": 410458, "channelDescription": "...", "numberOfSubscribers": 13100000, "channelTotalVideos": 409, "channelTotalViews": "1,710,167,563", "channelJoinedDate": "Mar 18, 2015", "channelLocation": "France", "inputChannelUrl": "https://www.youtube.com/@LofiGirl/about" } ``` #### Search / playlist item ```json { "id": "CwRMBKk8St0", "title": "LET'S ARGUE: Beyoncé Fails the Bechdel Test!", "duration": "13:48", "channelName": "fantano", "channelUrl": "https://www.youtube.com/@fantano", "date": "5 years ago", "url": "https://www.youtube.com/watch?v=CwRMBKk8St0", "viewCount": 635379, "fromYTUrl": "https://www.youtube.com/results?search_query=bechdel+test" } ``` #### Error item ```json { "url": "https://www.youtube.com/@somechannel", "input": "somechannel", "error": "CHANNEL_DOES_NOT_EXIST", "note": "Channel does not exist" } ``` #### Error codes | Code | Meaning | |------|---------| | `CHANNEL_DOES_NOT_EXIST` | Channel URL points to a channel that does not exist | | `NOT_FOUND` | Page was not found | | `VIDEO_UNAVAILABLE` | Video is not available (deleted, region-blocked, etc.) | | `AGE_RESTRICTED` | Channel is age-restricted and cannot be accessed without login | | `CHANNEL_HAS_NO_VIDEOS` | Channel exists but has no uploaded videos | | `CHANNEL_HAS_NO_LIVE_VIDEOS` | Channel exists but has no live videos | | `CHANNEL_HAS_NO_SHORTS` | Channel exists but has no Shorts | | `DATE_FILTER_TOO_STRICT` | Videos exist but none match the active date filter | | `NO_VIDEOS` | No videos found on the page | | `NO_RESULTS` | No results collected — check that video-type limits are set above 0 | | `NO_VALID_START_URLS` | All provided start URLs were invalid or malformed | | `INVALID_INPUT` | Actor failed due to bad configuration | | `NO_COMMENTS` | No comments found for the video | # Actor input Schema ## `startUrls` (type: `array`): Direct URLs of YouTube videos, channels, playlists or search result pages. You can mix all types. ## `searchQueries` (type: `array`): Keywords, exactly as you would type them into the YouTube search bar. ## `maxResults` (type: `integer`): How many regular videos to scrape per URL or search term. Set 0 to exclude regular videos from search results. ## `maxResultsShorts` (type: `integer`): How many Shorts to scrape per search term (search terms only). Set 0 to exclude Shorts. ## `maxResultStreams` (type: `integer`): How many live streams to scrape per search term (search terms only). Set 0 to exclude streams. ## `sortingOrder` (type: `string`): How YouTube should sort the search results. ## `dateFilter` (type: `string`): Only return videos published within the selected period. ## `oldestPostDate` (type: `string`): Only keep videos published after this date. Accepts an absolute date (e.g. "2024-01-31") or a relative period (e.g. "2 weeks", "3 months"). ## `sortVideosBy` (type: `string`): Order used on the channel Videos tab before collecting. ## `downloadSubtitles` (type: `boolean`): If enabled, every collected video is opened in detail and its subtitles are attached to the output item. ## `saveSubsToKVS` (type: `boolean`): Also persist each downloaded subtitle file to the run's key-value store (for later use in other Actors or automations). ## `subtitlesLanguage` (type: `string`): Preferred subtitles language. "Any" picks the first available track. ## `subtitlesFormat` (type: `string`): Format of the downloaded subtitles. ## `preferAutoGeneratedSubtitles` (type: `boolean`): Pick the auto-generated track even when a user-created one exists. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.youtube.com/@LofiGirl" } ], "searchQueries": [ "lofi hip hop" ], "maxResults": 10, "maxResultsShorts": 10, "maxResultStreams": 10, "sortingOrder": "relevance", "sortVideosBy": "NEWEST", "downloadSubtitles": false, "saveSubsToKVS": false, "subtitlesLanguage": "any", "subtitlesFormat": "srt", "preferAutoGeneratedSubtitles": false } ``` # Actor output Schema ## `results` (type: `string`): Dataset containing scraped YouTube videos, channels, playlists, and search results. # 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/@LofiGirl" } ], "searchQueries": [ "lofi hip hop" ] }; // Run the Actor and wait for it to finish const run = await client.actor("lisbuenas/youtube-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/@LofiGirl" }], "searchQueries": ["lofi hip hop"], } # Run the Actor and wait for it to finish run = client.actor("lisbuenas/youtube-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/@LofiGirl" } ], "searchQueries": [ "lofi hip hop" ] }' | apify call lisbuenas/youtube-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lisbuenas/youtube-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Youtube Scraper", "description": "YouTube Scraper extracts bulk public data beyond official API limits. Grab video metadata, view counts, comments, and live like counters from channels, playlists, streams, and search results. Export to JSON, CSV, or Excel via API endpoints, webhooks, or our Python & Node.js SDKs.", "version": "0.0", "x-build-id": "o7tIcidSTCyiphjG2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lisbuenas~youtube-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lisbuenas-youtube-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/lisbuenas~youtube-scraper/runs": { "post": { "operationId": "runs-sync-lisbuenas-youtube-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/lisbuenas~youtube-scraper/run-sync": { "post": { "operationId": "run-sync-lisbuenas-youtube-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 URLs", "type": "array", "description": "Direct URLs of YouTube videos, channels, playlists or search result pages. You can mix all types.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "Search terms", "type": "array", "description": "Keywords, exactly as you would type them into the YouTube search bar.", "items": { "type": "string" } }, "maxResults": { "title": "Maximum number of videos", "minimum": 0, "type": "integer", "description": "How many regular videos to scrape per URL or search term. Set 0 to exclude regular videos from search results.", "default": 10 }, "maxResultsShorts": { "title": "Maximum number of Shorts", "minimum": 0, "type": "integer", "description": "How many Shorts to scrape per search term (search terms only). Set 0 to exclude Shorts.", "default": 10 }, "maxResultStreams": { "title": "Maximum number of streams", "minimum": 0, "type": "integer", "description": "How many live streams to scrape per search term (search terms only). Set 0 to exclude streams.", "default": 10 }, "sortingOrder": { "title": "Sorting order", "enum": [ "relevance", "upload_date", "view_count", "rating" ], "type": "string", "description": "How YouTube should sort the search results.", "default": "relevance" }, "dateFilter": { "title": "Date filter", "enum": [ "hour", "today", "week", "month", "year" ], "type": "string", "description": "Only return videos published within the selected period." }, "oldestPostDate": { "title": "Date range (applicable only to scraping by channels URL)", "type": "string", "description": "Only keep videos published after this date. Accepts an absolute date (e.g. \"2024-01-31\") or a relative period (e.g. \"2 weeks\", \"3 months\")." }, "sortVideosBy": { "title": "Sort channel videos by", "enum": [ "NEWEST", "POPULAR", "OLDEST" ], "type": "string", "description": "Order used on the channel Videos tab before collecting.", "default": "NEWEST" }, "downloadSubtitles": { "title": "Download subtitles", "type": "boolean", "description": "If enabled, every collected video is opened in detail and its subtitles are attached to the output item.", "default": false }, "saveSubsToKVS": { "title": "Save subtitles to key-value store", "type": "boolean", "description": "Also persist each downloaded subtitle file to the run's key-value store (for later use in other Actors or automations).", "default": false }, "subtitlesLanguage": { "title": "Subtitles language", "enum": [ "any", "en", "es", "pt", "fr", "de", "it", "ja", "ko", "ru", "hi", "ar" ], "type": "string", "description": "Preferred subtitles language. \"Any\" picks the first available track.", "default": "any" }, "subtitlesFormat": { "title": "Subtitles format", "enum": [ "srt", "vtt", "xml", "plaintext" ], "type": "string", "description": "Format of the downloaded subtitles.", "default": "srt" }, "preferAutoGeneratedSubtitles": { "title": "Prefer auto-generated subtitles", "type": "boolean", "description": "Pick the auto-generated track even when a user-created one exists.", "default": false } } }, "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 } } } } } } } } } } ```