# YouTube Search Results Scraper (`automly/youtube-search-results-scraper`) Actor Search YouTube and collect ranked video, channel, and playlist results for any list of queries as clean, flat records — built for content research, SEO, lead discovery, and trend monitoring. - **URL**: https://apify.com/automly/youtube-search-results-scraper.md - **Developed by:** [Automly](https://apify.com/automly) (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 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 ## YouTube Search Results Scraper Search YouTube for any list of queries and get back **ranked, normalized results** — videos, channels, and playlists — as clean, flat records. Built for content research, SEO and keyword intelligence, lead and creator discovery, and trend monitoring. For every query you get one row per result, tagged with the query and its rank, including the title, link, channel, view count, publish time, duration, thumbnail, and badges. ### What it does - Searches YouTube for each query you provide and collects the results in order. - Returns **videos, channels, and playlists** — pick the types you want. - Filters by **sort order** (relevance, upload date, view count, rating), **upload date**, and **video duration**. - Paginates through multiple pages to reach the number of results you ask for. - De-duplicates results and strictly caps each query at your chosen maximum. - Optionally enriches each channel with subscriber count, description, and avatar. - Works **without any API key**. Optionally switch to the official YouTube Data API by supplying your own key. ### Input | Field | Type | Description | | --- | --- | --- | | `queries` | array | **Required.** Search phrases, one per line. | | `resultTypes` | array | Which kinds to keep: `video`, `channel`, `playlist`. Defaults to `video`. | | `maxResults` | integer | Maximum results per query (1–1000). Default `50`. | | `sortBy` | string | `relevance`, `date`, `viewCount`, or `rating`. Default `relevance`. | | `uploadDate` | string | `any`, `hour`, `today`, `week`, `month`, `year`. Videos only. | | `duration` | string | `any`, `short` (<4 min), `medium` (4–20 min), `long` (>20 min). Videos only. | | `language` | string | Two-letter interface language code (e.g. `en`). Default `en`. | | `country` | string | Two-letter market country code (e.g. `us`). Default `us`. | | `includeThumbnails` | boolean | Include the best thumbnail URL. Default `true`. | | `includeChannelDetails` | boolean | Enrich each channel with subscriber count, description, and avatar. Default `false`. | | `youtubeApiKey` | string | Optional YouTube Data API v3 key for official API mode. | | `proxyConfiguration` | object | Proxy settings. A residential proxy is recommended for the most reliable, location-accurate results. | #### Example input ```json { "queries": ["apify tutorial", "web scraping python"], "resultTypes": ["video"], "maxResults": 25, "sortBy": "viewCount", "uploadDate": "year", "language": "en", "country": "us" } ```` ### Output Each dataset item is one result. Example (abbreviated): ```json { "query": "apify tutorial", "rank": 1, "resultKind": "video", "itemId": "3rrpfW0bEdc", "videoId": "3rrpfW0bEdc", "title": "Apify Tutorial For Beginners | How To Use Apify", "url": "https://www.youtube.com/watch?v=3rrpfW0bEdc", "channelName": "Speak About Digital", "channelUrl": "https://www.youtube.com/@SpeakAboutDigital", "channelId": "UCqD-h6ucBDUntfoapPyhp0Q", "publishedText": "2 years ago", "duration": "10:41", "durationSeconds": 641, "viewCountText": "36,042 views", "viewCount": 36042, "descriptionSnippet": "Apify Tutorial For Beginners | How To Use Apify…", "thumbnailUrl": "https://i.ytimg.com/vi/3rrpfW0bEdc/hq720.jpg", "isShort": false, "isLive": false, "badges": [], "fetchedAt": "2026-06-06T11:32:05Z" } ``` Channel and playlist results use the same shape: channels populate `channelId`, `subscriberCountText`/`subscriberCount`, and `videoCount`; playlists populate `playlistId` and `videoCount`. #### Key output fields `query`, `rank`, `resultKind`, `itemId`, `videoId` / `channelId` / `playlistId`, `title`, `url`, `channelName`, `channelUrl`, `publishedText`, `publishedAt`, `duration`, `durationSeconds`, `viewCountText`, `viewCount`, `descriptionSnippet`, `thumbnailUrl`, `isShort`, `isLive`, `badges`, `subscriberCountText`, `subscriberCount`, `videoCount`, `channelDescription`, `channelThumbnailUrl`, `fetchedAt`. ### Use cases - **Content research** — discover the top videos and creators for a topic. - **SEO & keyword intelligence** — track which videos rank for your target queries over time. - **Lead & creator discovery** — find channels and playlists in a niche. - **Trend monitoring** — watch what's newest or most viewed for a query on a schedule. ### Tips - For monitoring, schedule the actor and filter by `uploadDate` to capture only fresh results. - A residential proxy gives the most consistent, location-accurate results, especially at higher volumes. - Results reflect what YouTube returns for the given language and country, which can differ by market. ### Notes This actor collects only **public** search results. It does not log in and does not access private or restricted content. YouTube only exposes a relative publish time (e.g. "2 years ago") in search; an absolute `publishedAt` is available when you run in official API mode with your own key. # Actor input Schema ## `queries` (type: `array`): One or more phrases to search on YouTube. Each query is searched independently and every result is tagged with the query it came from. ## `resultTypes` (type: `array`): Which kinds of results to keep. Accepted values are 'video', 'channel', and 'playlist' (one per line). When exactly one type is chosen, the search is filtered to that type; with several types the actor keeps all of the chosen kinds. Defaults to videos only. ## `maxResults` (type: `integer`): Maximum number of results to collect for each query (1-1000). Lower values run faster. ## `sortBy` (type: `string`): Ordering of the results. 'Relevance' mirrors YouTube's default ranking; the others reorder by upload date, view count, or rating. ## `uploadDate` (type: `string`): Restrict video results to a recent time window. Applies to videos only; ignored for channels and playlists. ## `duration` (type: `string`): Restrict video results by length. 'Short' is under 4 minutes, 'Medium' is 4-20 minutes, 'Long' is over 20 minutes. Applies to videos only. ## `language` (type: `string`): Two-letter interface language code (for example: en, es, de, fr, pt). Affects localized labels such as relative dates. ## `country` (type: `string`): Two-letter country code for the result market (for example: us, gb, de, fr, in, ca, au). ## `includeThumbnails` (type: `boolean`): When enabled, each result includes the best available thumbnail image URL. ## `includeChannelDetails` (type: `boolean`): When enabled, each unique channel is enriched once with extra details (subscriber count, description, and avatar). This adds extra requests, so runs take longer. ## `youtubeApiKey` (type: `string`): Optional. Provide a YouTube Data API v3 key to collect results through the official API instead of public search. Leave empty to use the default key-free mode. ## `proxyConfiguration` (type: `object`): Proxy settings used to reach YouTube. A residential proxy gives the most reliable, location-accurate results. Leave at the default to use the recommended setup. ## Actor input object example ```json { "queries": [ "apify tutorial", "how to scrape websites" ], "resultTypes": [ "video" ], "maxResults": 50, "sortBy": "relevance", "uploadDate": "any", "duration": "any", "language": "en", "country": "us", "includeThumbnails": true, "includeChannelDetails": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): All search results produced by this run. ## `overview` (type: `string`): Dataset presented using the overview view. # 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 = { "queries": [ "apify tutorial", "how to scrape websites" ], "resultTypes": [ "video" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("automly/youtube-search-results-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 = { "queries": [ "apify tutorial", "how to scrape websites", ], "resultTypes": ["video"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("automly/youtube-search-results-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 '{ "queries": [ "apify tutorial", "how to scrape websites" ], "resultTypes": [ "video" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call automly/youtube-search-results-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automly/youtube-search-results-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Search Results Scraper", "description": "Search YouTube and collect ranked video, channel, and playlist results for any list of queries as clean, flat records — built for content research, SEO, lead discovery, and trend monitoring.", "version": "1.0", "x-build-id": "qXpNUftSAHI4y6mfw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automly~youtube-search-results-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automly-youtube-search-results-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/automly~youtube-search-results-scraper/runs": { "post": { "operationId": "runs-sync-automly-youtube-search-results-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/automly~youtube-search-results-scraper/run-sync": { "post": { "operationId": "run-sync-automly-youtube-search-results-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", "required": [ "queries" ], "properties": { "queries": { "title": "Search queries", "minItems": 1, "type": "array", "description": "One or more phrases to search on YouTube. Each query is searched independently and every result is tagged with the query it came from.", "items": { "type": "string" } }, "resultTypes": { "title": "Result types", "type": "array", "description": "Which kinds of results to keep. Accepted values are 'video', 'channel', and 'playlist' (one per line). When exactly one type is chosen, the search is filtered to that type; with several types the actor keeps all of the chosen kinds. Defaults to videos only.", "items": { "type": "string" } }, "maxResults": { "title": "Max results per query", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of results to collect for each query (1-1000). Lower values run faster.", "default": 50 }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "date", "viewCount", "rating" ], "type": "string", "description": "Ordering of the results. 'Relevance' mirrors YouTube's default ranking; the others reorder by upload date, view count, or rating.", "default": "relevance" }, "uploadDate": { "title": "Upload date", "enum": [ "any", "hour", "today", "week", "month", "year" ], "type": "string", "description": "Restrict video results to a recent time window. Applies to videos only; ignored for channels and playlists.", "default": "any" }, "duration": { "title": "Video duration", "enum": [ "any", "short", "medium", "long" ], "type": "string", "description": "Restrict video results by length. 'Short' is under 4 minutes, 'Medium' is 4-20 minutes, 'Long' is over 20 minutes. Applies to videos only.", "default": "any" }, "language": { "title": "Language", "type": "string", "description": "Two-letter interface language code (for example: en, es, de, fr, pt). Affects localized labels such as relative dates.", "default": "en" }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for the result market (for example: us, gb, de, fr, in, ca, au).", "default": "us" }, "includeThumbnails": { "title": "Include thumbnails", "type": "boolean", "description": "When enabled, each result includes the best available thumbnail image URL.", "default": true }, "includeChannelDetails": { "title": "Include channel details", "type": "boolean", "description": "When enabled, each unique channel is enriched once with extra details (subscriber count, description, and avatar). This adds extra requests, so runs take longer.", "default": false }, "youtubeApiKey": { "title": "YouTube Data API key (optional)", "type": "string", "description": "Optional. Provide a YouTube Data API v3 key to collect results through the official API instead of public search. Leave empty to use the default key-free mode." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings used to reach YouTube. A residential proxy gives the most reliable, location-accurate results. Leave at the default to use the recommended setup." } } }, "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 } } } } } } } } } } ```