# YouTube Search Scraper (`skcho/youtube-scraper-enterprise`) Actor An optimized YouTube scraper to search videos, shorts, and streams by keywords, playlists, or channel URLs. Extract rich metadata, views, likes, and download subtitles/transcripts automatically. - **URL**: https://apify.com/skcho/youtube-scraper-enterprise.md - **Developed by:** [seungkyu cho](https://apify.com/skcho) (community) - **Categories:** Social media, Videos, Automation - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 ## 🚀 Premium YouTube Search Scraper (v1.0.0) [![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue?style=for-the-badge&logo=apify)](https://apify.com) [![Node.js](https://img.shields.io/badge/Node.js-22-green?style=for-the-badge&logo=node.js)](https://nodejs.org) [![Playwright](https://img.shields.io/badge/Playwright-1.49-orange?style=for-the-badge&logo=playwright)](https://playwright.dev) A highly optimized, production-ready **YouTube Search Scraper** designed to extract detailed metadata from YouTube searches, playlists, channels, and individual watch pages. Combining high-performance HTTP requests with Playwright stealth browser automation, it delivers maximum speed and reliability at a minimal memory footprint. --- ### 🌟 Key Selling Points & Advantages * **⚡ Hybrid Scraping Engine**: Extremely cost-efficient. Simple searches and watch pages are scraped via fast HTTP InnerTube API protocols (consuming minimal RAM). Playwright is activated *only* for rendering complex channels and playlists. * **🌐 Expose Localization Options (`hl` & `gl`)**: Target country-specific search relevance, regional trending orders, and retrieve localized metadata (e.g. original titles in Korean, Japanese, or French instead of forced English translations). * **🕒 Absolute Timestamp Interpolation**: Automatically converts relative times (e.g., `"3 days ago"`, `"16 hours ago"`) into precise, query-relative absolute Unix Epoch timestamps (`interpolatedTimestamp`). * **💬 Subtitle & Captions Downloader**: Supports downloading full transcripts and subtitles in multiple formats (`SRT`, `WebVTT`, `JSON`, `Plain Text`). * **🧠 Low Memory Footprint (V8 GC Enabled)**: Regularly invokes garbage collection at task boundaries to prevent container OOMs, running comfortably on 256MB or 512MB RAM instances to minimize platform costs. * **🛡️ Strict Anti-Bot Bypass**: Out-of-the-box support for user-agent rotation, stealth browser fingerprinting, and Apify Residential Proxies to dodge YouTube's rate limiting and CAPTCHAs. --- ### 🏗️ Technical Architecture ```mermaid graph TD A[Input JSON Config] --> B{Task Distributor} B -- "Search Query / Search URL" --> C[HTTP InnerTube API - Ultra Fast] B -- "Channel Handle / Playlist URL" --> D[Playwright Stealth Browser] C --> E[Video IDs & Search Metadata] D --> E E --> F[Stage 2: Deep Watch Page Extraction] F --> G[Extract InnerTube Player Details: Views, Likes, Description] F --> H[Extract Captions / Subtitles if enabled] G --> I[Relational Timestamp Interpolator] H --> J[Compile Dataset Item] I --> J J --> K[Push to Apify Dataset] K --> L[V8 Garbage Collection Memory Cleanup] ```` *** ### ⚙️ Input Parameters The Actor accepts a highly configurable JSON object. Below are the key parameters available: | Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | **`searchQueries`** | `array` | `["SpaceX", "Blue Origin"]` | Search keywords or phrases to query. | | **`startUrls`** | `array` | `[]` | Direct YouTube URLs to scrape (supports Video, Channel, or Playlist links). | | **`maxResults`** | `integer` | `50` | Maximum standard video results to scrape per search query or channel. | | **`maxResultsShorts`** | `integer` | `0` | Maximum Shorts to scrape per query/channel. | | **`maxResultStreams`** | `integer` | `0` | Maximum Live Streams to scrape per query/channel. | | **`downloadSubtitles`** | `boolean` | `false` | If enabled, extracts video subtitles/transcripts. | | **`subtitlesFormat`** | `string` | `"srt"` | Subtitle output format (`srt`, `vtt`, `txt`, `json`). | | **`sortingOrder`** | `string` | `"relevance"` | Sort results by `relevance`, `popularity` (views), `uploadDate`, or `rating`. | | **`dateFilter`** | `string` | `"any"` | Filter by upload date (`any`, `hour`, `today`, `thisWeek`, `thisMonth`, `thisYear`). | | **`lengthFilter`** | `string` | `"any"` | Filter by duration (`any`, `under4` mins, `between420` mins, `over20` mins). | | **`hl`** | `string` | `"en"` | Language code for YouTube client and translation UI. | | **`gl`** | `string` | `"US"` | Geographical region code for search relevance & localization. | | **`proxyConfiguration`** | `object` | `{"useApifyProxy": true}` | Proxy configuration. Residential proxies are highly recommended. | > \[!IMPORTANT] > When scraping regional keywords, match `hl` and `gl` to the target market (e.g., `hl: "ko"`, `gl: "KR"` for South Korea) to retrieve accurate search results and localized metadata. *** ### 📦 Output Format The Actor pushes scraped data to the default Apify Dataset. Below is the schema structure and description: | Field | Type | Description | | :--- | :--- | :--- | | `id` | `string` | Unique YouTube Video ID | | `url` | `string` | Video watch page URL | | `title` | `string` | Video title | | `description` | `string` | Full video description text | | `thumbnailUrl` | `string` | Highest resolution thumbnail URL | | `channelName` | `string` | Creator's channel name | | `channelUrl` | `string` | Creator's channel URL | | `channelId` | `string` | Creator's channel ID | | `channelSubscriberCount`| `string` | Creator's channel subscriber count | | `lengthSeconds` | `integer` | Video duration in seconds | | `viewCount` | `integer` | Number of video views | | `likes` | `integer` | Number of video likes | | `publishedDate` | `string` | ISO format upload timestamp | | `publishedTimeText` | `string` | Relative time text (e.g. `"2 days ago"`) | | `interpolatedTimestamp` | `integer` | Absolute Unix epoch timestamp (ms) | | `badges` | `array` | Video format badges (e.g., `["4K", "CC", "Shorts"]`) | | `transcript` | `string` | Extracted subtitles/transcripts (if `downloadSubtitles: true`) | | `subtitlesLanguage` | `string` | Language code of the downloaded transcript | #### 📄 Output JSON Example ```json [ { "id": "R8m3G1E4s-g", "url": "https://www.youtube.com/watch?v=R8m3G1E4s-g", "title": "SpaceX Starship Test Flight 4 Launch", "description": "Watch SpaceX launch Starship Flight 4 from Starbase, Texas...", "thumbnailUrl": "https://i.ytimg.com/vi/R8m3G1E4s-g/maxresdefault.jpg", "channelName": "SpaceX", "channelUrl": "https://www.youtube.com/@SpaceX", "channelId": "UC3xYfSxxxxxxx", "channelSubscriberCount": "15.4M subscribers", "lengthSeconds": 3600, "viewCount": 2450000, "likes": 120000, "publishedDate": "2026-06-25T12:00:00.000Z", "publishedTimeText": "2 days ago", "interpolatedTimestamp": 1744027200000, "badges": ["4K", "CC"], "transcript": null, "subtitlesLanguage": null } ] ``` *** ### 🚀 Execution & Integration #### Using Apify Client (Node.js) ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('your-username/youtube-search-scraper').call({ searchQueries: ["SpaceX"], maxResults: 20, hl: "en", gl: "US", proxyConfiguration: { useApifyProxy: true, apifyProxyGroups: ["RESIDENTIAL"] } }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(`Scraped ${items.length} videos!`); ``` #### Local Development 1. Install dependencies: ```bash npm install ``` 2. Modify variables inside `input.json` to customize parameters. 3. Run the actor locally: ```bash npm start ``` 4. Run integration tests: ```bash npm test ``` *** ### 🛡️ License & Disclaimers - **License**: MIT - **Disclaimer**: This actor is designed for research, data analysis, and archiving purposes. Please respect YouTube's Terms of Service and robot.txt rules when designing your scraping workflows. # Actor input Schema ## `searchQueries` (type: `array`): Provide keywords or search queries to run on YouTube. You can add multiple queries. E.g., \['SpaceX', 'Blue Origin']. ## `startUrls` (type: `array`): Direct YouTube URLs to scrape (Video, Channel, or Playlist URLs). Example: https://www.youtube.com/watch?v=lawvcQd3syc ## `maxResults` (type: `integer`): Maximum number of standard videos to scrape per search query or channel. ## `maxResultsShorts` (type: `integer`): Maximum number of Shorts videos to scrape per search query or channel. ## `maxResultStreams` (type: `integer`): Maximum number of Live Stream videos to scrape per search query or channel. ## `downloadSubtitles` (type: `boolean`): If enabled, extracts video subtitles/transcripts. ## `subtitlesLanguage` (type: `string`): Language code for the subtitles to download (e.g. en, ko, ja). ## `subtitlesFormat` (type: `string`): Select the format for extracted transcripts. ## `sortingOrder` (type: `string`): Sort search results by different criteria. ## `dateFilter` (type: `string`): Filter results by their upload date. ## `lengthFilter` (type: `string`): Filter results by their duration. ## `hl` (type: `string`): Language code for YouTube client headers and results (e.g. 'en' for English, 'ko' for Korean, 'ja' for Japanese). ## `gl` (type: `string`): Geographical region code for YouTube search relevance and country-specific content (e.g. 'US' for United States, 'KR' for South Korea, 'JP' for Japan). ## `proxyConfiguration` (type: `object`): Proxy settings to avoid IP bans. Defaulting to Apify Proxy is highly recommended for stability. ## Actor input object example ```json { "searchQueries": [ "SpaceX", "Blue Origin" ], "startUrls": [], "maxResults": 10, "maxResultsShorts": 0, "maxResultStreams": 0, "downloadSubtitles": false, "subtitlesLanguage": "en", "subtitlesFormat": "srt", "sortingOrder": "relevance", "dateFilter": "any", "lengthFilter": "any", "hl": "en", "gl": "US", "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `itemsDatasetUrl` (type: `string`): URL to the dataset containing the scraped YouTube video metadata. # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("skcho/youtube-scraper-enterprise").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 = {} # Run the Actor and wait for it to finish run = client.actor("skcho/youtube-scraper-enterprise").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 '{}' | apify call skcho/youtube-scraper-enterprise --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=skcho/youtube-scraper-enterprise", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Search Scraper", "description": "An optimized YouTube scraper to search videos, shorts, and streams by keywords, playlists, or channel URLs. Extract rich metadata, views, likes, and download subtitles/transcripts automatically.", "version": "0.0", "x-build-id": "Yn3WUk87LVM7nZ84j" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/skcho~youtube-scraper-enterprise/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-skcho-youtube-scraper-enterprise", "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/skcho~youtube-scraper-enterprise/runs": { "post": { "operationId": "runs-sync-skcho-youtube-scraper-enterprise", "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/skcho~youtube-scraper-enterprise/run-sync": { "post": { "operationId": "run-sync-skcho-youtube-scraper-enterprise", "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": { "searchQueries": { "title": "Search queries", "type": "array", "description": "Provide keywords or search queries to run on YouTube. You can add multiple queries. E.g., ['SpaceX', 'Blue Origin'].", "default": [ "SpaceX", "Blue Origin" ], "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Direct YouTube URLs to scrape (Video, Channel, or Playlist URLs). Example: https://www.youtube.com/watch?v=lawvcQd3syc", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxResults": { "title": "Maximum videos per search term", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Maximum number of standard videos to scrape per search query or channel.", "default": 10 }, "maxResultsShorts": { "title": "Maximum shorts per search term", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Maximum number of Shorts videos to scrape per search query or channel.", "default": 0 }, "maxResultStreams": { "title": "Maximum streams per search term", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Maximum number of Live Stream videos to scrape per search query or channel.", "default": 0 }, "downloadSubtitles": { "title": "Download Subtitles", "type": "boolean", "description": "If enabled, extracts video subtitles/transcripts.", "default": false }, "subtitlesLanguage": { "title": "Subtitles Language", "type": "string", "description": "Language code for the subtitles to download (e.g. en, ko, ja).", "default": "en" }, "subtitlesFormat": { "title": "Subtitles Format", "enum": [ "srt", "vtt", "txt", "json" ], "type": "string", "description": "Select the format for extracted transcripts.", "default": "srt" }, "sortingOrder": { "title": "Search Sorting Order", "enum": [ "relevance", "popularity", "uploadDate", "rating" ], "type": "string", "description": "Sort search results by different criteria.", "default": "relevance" }, "dateFilter": { "title": "Upload Date Filter", "enum": [ "any", "hour", "today", "thisWeek", "thisMonth", "thisYear" ], "type": "string", "description": "Filter results by their upload date.", "default": "any" }, "lengthFilter": { "title": "Video Duration Filter", "enum": [ "any", "under4", "between420", "over20" ], "type": "string", "description": "Filter results by their duration.", "default": "any" }, "hl": { "title": "Language Code (hl)", "type": "string", "description": "Language code for YouTube client headers and results (e.g. 'en' for English, 'ko' for Korean, 'ja' for Japanese).", "default": "en" }, "gl": { "title": "Country Code (gl)", "type": "string", "description": "Geographical region code for YouTube search relevance and country-specific content (e.g. 'US' for United States, 'KR' for South Korea, 'JP' for Japan).", "default": "US" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings to avoid IP bans. Defaulting to Apify Proxy is highly recommended for stability.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```