# YouTube Search Scraper (`apihq/youtube-search-scraper`) Actor Search YouTube and export results to JSON by keyword. No YouTube Data API key or quota. One record per result (video, channel, or playlist) with title, views, and channel. Filter by type, date, and duration. Queries that return nothing are free. $0.20 per 1,000 results. - **URL**: https://apify.com/apihq/youtube-search-scraper.md - **Developed by:** [apihq](https://apify.com/apihq) (community) - **Categories:** Social media, Videos, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $0.20 / 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 Search Scraper Search YouTube and export the results as clean JSON from a keyword. No YouTube Data API key, no quota, no browser. The contract is simple: **a query that finds nothing never fails your run, and you only pay for results delivered.** Search a batch of keywords, filter by type, date, or duration, and get one row per result. Pay-per-result at $0.20 per 1,000 results. Queries that return nothing cost $0. ### See one run Input: ```json { "queries": ["lofi hip hop", "synthwave"], "type": "video", "sortBy": "views", "uploadDate": "month", "duration": "long", "maxResults": 5 } ```` What comes back: - Up to 5 `success: true` video rows per query, billed: the most-viewed long lofi and synthwave videos from the past month - Each row carries the video, its channel, views, and thumbnail - Run status: **SUCCEEDED** - Charged: up to 10 results = $0.002 `query` alone works too. Every knob above is optional: `type` (videos, channels, or playlists), `sortBy` (relevance, date, views, or rating), `uploadDate` (last hour through this year), and `duration` (short, medium, or long). A query that returns nothing is a free `success: false` row, so one miss never blocks the batch. ### Why this Actor - **No YouTube Data API key or quota.** Many search workflows lean on Google's official Data API, with its keys to provision, daily quota accounting, and per-call limits. This Actor reads YouTube's public search directly, so there is no key to provision and no quota to ration, and it returns as many results as YouTube serves for the query. - **You pay only for results.** Billing fires on an explicit per-result event, not on dataset writes, so a query that returns nothing sits in your dataset for free. There is no per-run start fee, so an empty run costs zero. - **A bad filter never breaks the batch.** An unusable filter value or a query that finds nothing returns a `success: false` record with a machine-readable `code` (`NO_RESULTS`, `VALIDATION_FAILED`, `SEARCH_TIMEOUT`, `DEADLINE_EXCEEDED`). Branch on `code` without parsing English. ### Best for Data and AI workflows that turn a keyword into a dataset: competitor and market research, trend and topic discovery, tracking who ranks for a term, and collecting video IDs to feed transcript or comment jobs. The failure-free billing and machine-readable error rows matter most when the search runs unattended inside a larger pipeline, where one query with no results should never take down the batch. It works fine for one-off manual pulls too. ### Input example A single search, videos only: ```json { "query": "python tutorial", "type": "video", "maxResults": 100, "sortBy": "views", "uploadDate": "month" } ``` A batch of keywords: ```json { "queries": ["lofi hip hop", "synthwave", "jazz for studying"], "type": "video", "maxResults": 200 } ``` `query` and `queries` are merged and de-duplicated. Up to 50 unique queries run per job. Each query is walked page by page until it reaches `maxResults` or YouTube runs out of results. Filters (`type`, `sortBy`, `uploadDate`, `duration`) apply to every query in the run. ### Output example One record per result. The search term is copied onto every row so each row stands alone. A video result: ```json { "success": true, "result_type": "video", "search_query": "lofi hip hop", "video_id": "n61ULEU7CO0", "title": "Best of lofi hip hop 2021", "url": "https://www.youtube.com/watch?v=n61ULEU7CO0", "thumbnail_url": "https://i.ytimg.com/vi/n61ULEU7CO0/hqdefault.jpg", "view_count": "55,765,840 views", "published": "4 years ago", "duration": 22258, "is_live": false, "description_snippet": "The best lofi hip hop songs of 2021, all in one mix.", "channel_name": "Lofi Girl", "channel_id": "UCSJ4gkVC6NrvII8umztf0Ow", "channel_url": "https://www.youtube.com/@LofiGirl" } ``` A query that returns nothing lands in the same dataset and is not charged: ```json { "success": false, "search_query": "asdkjfhqwiuerypoxzcv", "code": "NO_RESULTS", "error": "Search returned no results for query: asdkjfhqwiuerypoxzcv", "request_id": "req_911f37d2e55644ff9d9e4a3f", "status_code": 404 } ``` Split hits from misses on the `success` field, and the kind of hit on `result_type`. Quote `request_id` in any support issue and we can trace the exact request. ### What you get Every result is one record with `success: true`. `result_type` tells you which kind, and which fields the row carries: | Field | Type | On which rows | What it is | |---|---|---|---| | `success` | boolean | all | `true` for a result (billed), `false` for a query that returned nothing (not billed). | | `result_type` | string | all | `video`, `channel`, `playlist`, or `shorts`. | | `search_query` | string | all | The search term that produced this row. | | `title` | string | all | Video/playlist title, or the channel name. | | `url` | string | all | Canonical URL of the result (watch, shorts, channel, or playlist). | | `thumbnail_url` | string | all | URL of the largest available thumbnail. May be empty. | | `video_id` | string | video, shorts | The 11-character video ID. | | `view_count` | string | video, shorts | View count as a display string. May be empty. | | `published` | string | video | Relative publish string (for example `5 years ago`). May be empty. | | `duration` | integer | video | Length in whole seconds. Absent for live streams. | | `is_live` | boolean | video | `true` for a live stream. | | `description_snippet` | string | video, channel | A short description excerpt. May be empty. | | `channel_name` | string | video, playlist | Uploader or owner name. | | `channel_id` | string | video, channel, playlist | The `UC...` channel ID, where available. | | `channel_url` | string | video | Uploader channel URL. May be empty. | | `channel_handle` | string | channel | The channel `@handle`. May be empty. | | `subscriber_text` | string | channel | Subscriber count as a display string (for example `506M subscribers`). | | `playlist_id` | string | playlist | The playlist ID. | | `video_count` | string | playlist | Playlist size as a display string (for example `34 videos`). | Queries that returned nothing carry `success: false`, `search_query`, a machine-readable `code`, a human-readable `error`, the service `request_id`, and the HTTP `status_code`. They are not charged. ### Pricing Pay-per-result. One charge per result delivered: `$0.0002` each, which is `$0.20 per 1,000 results`. The charge fires only after a result row lands in your dataset. - 1,000 delivered results cost $0.20. - A run whose queries all return nothing costs $0. - There is no per-run start fee, so an empty run is genuinely free. Apify subscriber discounts apply automatically: roughly `$0.16 per 1,000` on the Scale plan and `$0.12 per 1,000` on Business. Platform compute is included in the per-result price. Cap the maximum spend of a single run from Apify's Run Limits panel; the Actor honors the cap and stops cleanly mid-walk when the budget runs out. ### What this Actor does not do Honest scope, so you know before you run it: - **YouTube sets the depth, not you.** YouTube stops serving results for a query when relevance runs out, usually in the low hundreds. A high `maxResults` returns everything available, which for many queries is fewer than the number you asked for. This is not a fixed cap like the Data API's 500, but it is not unlimited either. - **`video` is the default and returns only videos.** Set `type` to `channel` or `playlist` for those, or `all` for a mix (which also surfaces Shorts). There is no standalone `shorts` type; Shorts appear under `all`. - **One row per result, with what search exposes.** You get the title, channel, views, and thumbnail search shows. Full descriptions, like counts, comment counts, and tags require opening each video and are out of scope here. - **Public results only.** The search returns what a signed-out visitor sees. ### How to use this Actor 1. Open the Actor in the Apify Console. 2. Set `query` (single), `queries` (a list), or both. Up to 50 unique queries run per job. 3. Set `maxResults` to cap results per query. Optionally set `type` (video, channel, playlist, or all), `sortBy` (relevance, date, views, rating), `uploadDate`, and `duration`. Filters apply to every query. 4. Click Start. Each result is one `success: true` record. Queries that return nothing produce one `success: false` record and do not stop the run. Only results are charged. The Actor is also callable from the Apify API and every official integration (Make, Zapier, n8n, Slack, webhooks). The API tab in the Console has ready-to-paste JavaScript, Python, and curl snippets. ### Reliability **A bad filter or a query with no results never fails the batch.** An unusable filter value or a query that finds nothing becomes a `success: false` record with a specific `code`. The run keeps going and finishes successfully. **You never pay for a miss.** Billing fires on an explicit per-result charge event, not on dataset writes, so `success: false` records are free. There is no per-run start fee either. **Hard 30-second deadline per page request.** Each page of results is fetched under a 30-second deadline. If YouTube or the proxy network stalls, that query returns a `504` with `code: DEADLINE_EXCEEDED` as a `success: false` record instead of hanging your run. ### FAQ **Do I need a YouTube Data API key?** No. The Actor reads YouTube's public search directly and does not consume Google API quota. **How many results can I get per query?** As many as YouTube serves for that term, capped by `maxResults`. YouTube stops paging when relevance runs out, which for most queries is in the low hundreds. There is no fixed 500-result ceiling like the official Data API, but no query is unlimited either. **Can I search for channels or playlists, not just videos?** Yes. Set `type` to `channel` or `playlist`. `all` returns a mix of videos, channels, playlists, and Shorts. The default, `video`, returns only videos. **Can I filter and sort?** Yes. `sortBy` takes relevance (default), date, views, or rating. `uploadDate` and `duration` narrow video results. Filters apply to every query in the run. **Why did I get fewer results than maxResults?** YouTube ran out of results for that query first. `maxResults` is a ceiling, not a guarantee; the depth of any search is set by YouTube, and the `video` filter is shallower than an unfiltered `all` search. **Can I also get transcripts, comments, or a channel's full uploads?** Yes, with the sibling Actors: [YouTube Transcript Scraper](https://apify.com/apihq/youtube-transcript-scraper) for captions, [YouTube Comments Scraper](https://apify.com/apihq/youtube-comments-scraper) for comments, [YouTube Channel Scraper](https://apify.com/apihq/youtube-channel-scraper) for a channel's videos, and [YouTube Shorts Scraper](https://apify.com/apihq/youtube-shorts-scraper) for Shorts. Search collects the video IDs; the sibling Actors go deep on each. **Can I use this Actor from my own code?** Yes. Use the Apify API or one of the official SDKs (Node.js: `apify-client`, Python: `apify-client`). The Console shows ready-to-paste code samples on the API tab. **How does billing know a query returned nothing?** Billing fires on an explicit per-result charge event, not on dataset writes. The Actor only fires it when a result is delivered, so `success: false` records sit in your dataset for free. You get every result in one place and still branch on `success` and `code`, with a `request_id` for support correlation. ### Found a bug or want a feature? Open an issue on this Actor's Issues tab and include the `request_id` from any error record you saw. We respond within one business day. # Actor input Schema ## `query` (type: `string`): A single YouTube search term (e.g. 'lofi hip hop'). An invalid filter value comes back as a success:false record (code VALIDATION\_FAILED), not a rejected run. ## `queries` (type: `array`): List of search terms. Merged with query and de-duplicated; up to 50 unique queries are processed per run. A query with no results comes back as a success:false record, so one miss never blocks the batch. ## `maxResults` (type: `integer`): Maximum number of results to return per query. The Actor walks result pages until it reaches this many results or YouTube runs out. How many YouTube serves varies by query (often a few hundred), so a very high value may return fewer. ## `type` (type: `string`): Which kind of result to return. 'video' (default) returns only videos; 'channel' and 'playlist' return those; 'all' returns a mix (including Shorts). ## `sortBy` (type: `string`): Result order. 'relevance' (default) is YouTube's ranking; the others sort by upload date, view count, or rating. ## `uploadDate` (type: `string`): Restrict video results by how recently they were uploaded. Only applies when type is 'video' or 'all'; ignored otherwise. ## `duration` (type: `string`): Restrict video results by length. Only applies when type is 'video' or 'all'; ignored otherwise. ## Actor input object example ```json { "query": "lofi hip hop", "maxResults": 100, "type": "video", "sortBy": "relevance", "uploadDate": "", "duration": "" } ``` # Actor output Schema ## `results` (type: `string`): One record per result. success:true carries the result fields; success:false carries the error code and message for a query that returned nothing or failed. # 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 = { "query": "lofi hip hop", "maxResults": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("apihq/youtube-search-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 = { "query": "lofi hip hop", "maxResults": 100, } # Run the Actor and wait for it to finish run = client.actor("apihq/youtube-search-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 '{ "query": "lofi hip hop", "maxResults": 100 }' | apify call apihq/youtube-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apihq/youtube-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Search Scraper", "description": "Search YouTube and export results to JSON by keyword. No YouTube Data API key or quota. One record per result (video, channel, or playlist) with title, views, and channel. Filter by type, date, and duration. Queries that return nothing are free. $0.20 per 1,000 results.", "version": "0.1", "x-build-id": "zFG4Etky9glCnuD38" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apihq~youtube-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apihq-youtube-search-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/apihq~youtube-search-scraper/runs": { "post": { "operationId": "runs-sync-apihq-youtube-search-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/apihq~youtube-search-scraper/run-sync": { "post": { "operationId": "run-sync-apihq-youtube-search-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": { "query": { "title": "Search query", "type": "string", "description": "A single YouTube search term (e.g. 'lofi hip hop'). An invalid filter value comes back as a success:false record (code VALIDATION_FAILED), not a rejected run." }, "queries": { "title": "Multiple queries", "type": "array", "description": "List of search terms. Merged with query and de-duplicated; up to 50 unique queries are processed per run. A query with no results comes back as a success:false record, so one miss never blocks the batch.", "items": { "type": "string" } }, "maxResults": { "title": "Max results per query", "type": "integer", "description": "Maximum number of results to return per query. The Actor walks result pages until it reaches this many results or YouTube runs out. How many YouTube serves varies by query (often a few hundred), so a very high value may return fewer." }, "type": { "title": "Result type", "enum": [ "video", "channel", "playlist", "all" ], "type": "string", "description": "Which kind of result to return. 'video' (default) returns only videos; 'channel' and 'playlist' return those; 'all' returns a mix (including Shorts).", "default": "video" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "date", "views", "rating" ], "type": "string", "description": "Result order. 'relevance' (default) is YouTube's ranking; the others sort by upload date, view count, or rating.", "default": "relevance" }, "uploadDate": { "title": "Upload date (videos only)", "enum": [ "", "hour", "today", "week", "month", "year" ], "type": "string", "description": "Restrict video results by how recently they were uploaded. Only applies when type is 'video' or 'all'; ignored otherwise.", "default": "" }, "duration": { "title": "Duration (videos only)", "enum": [ "", "short", "medium", "long" ], "type": "string", "description": "Restrict video results by length. Only applies when type is 'video' or 'all'; ignored otherwise.", "default": "" } } }, "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 } } } } } } } } } } ```