# YouTube Scraper Intelligence (`crowdpull/youtube-scraper-intelligence`) Actor Scrape public YouTube videos, Shorts, streams, channels, playlists, search results, subtitles, comments, and AI-ready transcript records. - **URL**: https://apify.com/crowdpull/youtube-scraper-intelligence.md - **Developed by:** [Crowd Pull](https://apify.com/crowdpull) (community) - **Categories:** Videos, Social media, Lead generation - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 1 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. 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 ### What does YouTube Scraper Intelligence do? [YouTube Scraper Intelligence](https://apify.com/crowdpull/youtube-scraper-intelligence) extracts public data from [YouTube](https://www.youtube.com) videos, Shorts, streams, channels, playlists, search results, hashtags, comments, and subtitles. It is built for teams that need more than a basic YouTube API replacement: content intelligence, brand monitoring, creator research, market research, and transcript pipelines. Start with YouTube URLs, search terms, channel handles, playlist links, Shorts links, or Trending. The Actor returns normalized video records with clear diagnostics, AI-ready transcript formats, optional full comments, deduplication, and compatibility fields for common YouTube scraper workflows. Use this Actor when you need to: - Monitor brands, products, topics, creators, or competitors on YouTube. - Collect video metadata, engagement metrics, channel details, subtitles, and comments in one run. - Build transcript datasets for search, RAG, summarization, sentiment analysis, or trend detection. - Run repeatable YouTube monitoring jobs with deduplication and changing metric refreshes. - Migrate from broad YouTube scraper inputs without rewriting your whole workflow. ### What YouTube data can you scrape? | Data type | Example fields | | --- | --- | | Video metadata | `id`, `url`, `title`, `description`, `hashtags`, `thumbnailUrl`, `duration`, `date` | | Engagement | `viewCount`, `likes`, `commentsCount`, `isMonetized`, `videoType` | | Channel data | `channelName`, `channelUrl`, `channelId`, `numberOfSubscribers`, `channelLocation`, `channelTotalVideos`, `channelTotalViews` | | Search and source context | `fromYTUrl`, `sourceType`, search filters, source diagnostics | | Subtitles and transcripts | manual captions, auto captions, SRT, VTT, XML, plain text, timestamped segments, KV-store URLs | | Comments | comment ID, text, author, author channel, timestamp, likes, parent ID, reply depth, sort mode | | Diagnostics | `status`, `errorCode`, `errorMessage`, subtitle errors, source-level summary records | ### Supported YouTube sources | Source | Supported | | --- | --- | | Direct video URLs | Yes | | YouTube Shorts URLs | Yes | | Channel URLs and handles | Yes | | Playlist URLs | Yes | | Search-result URLs | Yes | | Search terms | Yes | | Hashtag URLs | Yes | | Locale-aware Trending | Yes, with fallback diagnostics when YouTube redirects the public Trending page | ### Why use this YouTube scraper? Most YouTube scrapers stop at metadata, search results, or one transcript format. This Actor is designed as a broader intelligence crawler: - Broad crawler coverage: videos, Shorts, streams, channels, playlists, search URLs, search queries, hashtags, Trending, subtitles, and comments. - Search controls: relevance, upload date, views, relative date filters, custom dates, duration filters, HD, 4K, HDR, live, 3D, 360, VR180, subtitles, Creative Commons, location, and a compatibility-only purchased/premium filter. - Better transcript handling: manual captions first, auto-generated captions second, language fallback, SRT, VTT, XML, plain text, timestamped JSON segments, and optional Whisper fallback with spend caps. - Full comment controls: enable comments only when needed, choose top or newest sorting, and cap comments per video. - Stable output schema: video records are normalized so your downstream code is insulated from `yt-dlp` or YouTube field drift. - Monitoring built in: Smart Scrape dedup, recent metric refreshes, source-level `SUMMARY`, and `SOURCE_DIAGNOSTICS` records. ### How to scrape YouTube data 1. Open [YouTube Scraper Intelligence](https://apify.com/crowdpull/youtube-scraper-intelligence). 2. Add YouTube URLs, search terms, YouTube handles, or Trending. 3. Set result limits for regular videos, Shorts, and streams. 4. Turn subtitles and comments on or off depending on the job. 5. Run the Actor and export results from the dataset as JSON, CSV, Excel, HTML, XML, or through the Apify API. ### Input examples #### Search YouTube with comments and subtitles ```json { "searchQueries": ["bittensor", "bitcoin"], "maxResults": 25, "maxResultsShorts": 10, "sortBy": "uploadDate", "dateFilter": "month", "lengthFilter": "under4", "hasSubtitles": true, "includeSubtitles": true, "includeComments": true, "commentSort": "top", "maxCommentsPerVideo": 500 } ```` #### Monitor a YouTube channel for transcripts ```json { "youtubeHandles": ["@TED"], "maxResults": 50, "includeSubtitles": true, "languages": ["en.*"], "enableDedup": true, "refreshWindowDays": 7 } ``` #### Use keyword, locale, and feature filters ```json { "keywords": ["bittensor"], "youtubeHandles": ["@TED"], "getTrending": true, "gl": "US", "hl": "en", "maxItems": 5, "sort": "v", "uploadDate": "today", "duration": "short", "features": "hd,subtitles", "customMapFunction": "(item) => ({ id: item.id, title: item.title, views: item.views })" } ``` #### Use Whisper only when captions are unavailable ```json { "startUrls": [{ "url": "https://www.youtube.com/watch?v=VIDEO_ID" }], "includeSubtitles": true, "transcriptMode": "captionsThenWhisper", "openaiApiKey": "YOUR_OPENAI_API_KEY", "maxWhisperMinutesPerRun": 30, "maxAudioDurationMinutes": 20 } ``` ### Output example Each dataset item is a video-shaped record. Failed video or source extractions emit a diagnostic row instead of silently disappearing. ```json { "status": "succeeded", "id": "VIDEO_ID", "url": "https://www.youtube.com/watch?v=VIDEO_ID", "title": "Example YouTube video", "description": "Public video description", "hashtags": ["bittensor", "crypto"], "thumbnailUrl": "https://i.ytimg.com/vi/VIDEO_ID/maxresdefault.jpg", "duration": "00:12:34", "date": "2026-04-20", "viewCount": 123456, "likes": 3456, "commentsCount": 789, "channelName": "Example Channel", "channelUrl": "https://www.youtube.com/@example", "channelId": "UC...", "numberOfSubscribers": 100000, "videoType": "video", "subtitles": [ { "type": "manual", "language": "en", "format": "all", "plainText": "Transcript text...", "segments": [{ "start": 0.0, "end": 4.2, "text": "Transcript text..." }] } ], "comments": [ { "id": "COMMENT_ID", "text": "Public comment text", "author": "Comment Author", "authorChannelUrl": "https://www.youtube.com/channel/...", "timestamp": "2026-04-21T10:00:00Z", "likes": 12, "replyDepth": 0, "parentId": null, "sortMode": "top" } ], "sourceType": "search", "scrapedAt": "2026-04-26T12:00:00Z" } ``` ### Migration-friendly inputs This Actor accepts common broad-crawler fields: `sortingOrder`, `downloadSubtitles`, `saveSubsToKVS`, `subtitlesLanguage`, `preferAutoGeneratedSubtitles`, `subtitlesFormat`, `videoType`, `lengthFilter`, `isHD`, `hasSubtitles`, `hasCC`, `is3D`, `isLive`, `isBought`, `is4K`, `is360`, `hasLocation`, `isHDR`, `isVR180`, `oldestPostDate`, and `sortVideosBy`. It also accepts search, locale, and mapping aliases: `keywords`, `youtubeHandles`, `getTrending`, `gl`, `hl`, `maxItems`, `sort`, `uploadDate`, `duration`, `features`, and `customMapFunction`. Compatibility does not mean every private or unavailable YouTube signal can be scraped. Dislikes are not included because they are not public YouTube data. The purchased/premium input is accepted for workflow compatibility, but public unauthenticated YouTube search often returns no real video rows for it and public metadata does not reliably expose purchase availability. ### Pricing and performance notes This Actor uses premium pay-per-event pricing. The baseline metadata price is positioned for a full-featured YouTube crawler, while transcript rows carry premium pricing because they include richer subtitle formats and transcript-ready output. | Event | Price | Applies to | | --- | ---: | --- | | `video-scraped` | `$2.35 / 1,000 rows` | Successful video metadata rows without transcript payloads | | `transcript-captions` | `$4.90 / 1,000 rows` | Successful rows with public caption transcripts | | `transcript-whisper` | `$4.90 / 1,000 rows` | Successful rows with Whisper fallback transcripts | Whisper fallback requires the user's OpenAI API key. OpenAI API usage is billed to that key, not to this Actor. Platform compute, proxy, and storage usage may also apply depending on the user's Apify plan and run settings. Large comment jobs and transcript-heavy jobs cost more because they do more network and parsing work. For bigger monitoring runs, start with comments disabled, then enable comments on the channels or videos that matter. ### Published CrowdPull Actor lineup Use YouTube Scraper Intelligence alongside published CrowdPull Actors to build larger social, marketplace, hiring, and public-records workflows. | Workflow | CrowdPull Actors | | --- | --- | | Social intelligence | [Instagram Scraper](https://apify.com/crowdpull/instagram-scraper) | | Facebook research | [Facebook Profile Scraper](https://apify.com/crowdpull/facebook-profile-scraper), [Facebook Page Posts Scraper](https://apify.com/crowdpull/facebook-page-posts-scraper), [Facebook Group Posts Scraper](https://apify.com/crowdpull/facebook-group-posts-scraper), [Facebook Comment Scraper](https://apify.com/crowdpull/facebook-comment-scraper) | | Marketplace intelligence | [Facebook Marketplace Scraper](https://apify.com/crowdpull/facebook-marketplace-scraper), [OfferUp Scraper](https://apify.com/crowdpull/offerup-scraper), [AliExpress Reviews Scraper](https://apify.com/crowdpull/aliexpress-reviews-scraper) | | Hiring and labor market data | [ZipRecruiter Jobs Scraper](https://apify.com/crowdpull/crowdpull-ziprecruiter-jobs-scraper) | | Public records and compliance research | [OSHA Violations Scraper](https://apify.com/crowdpull/osha-violations-scraper) | ### API usage You can run this Actor from the Apify Console, API, CLI, schedules, webhooks, or SDKs. Dataset results are available from the default dataset, while run-level summary and diagnostics are available from the default key-value store. ```bash apify call crowdpull/youtube-scraper-intelligence --input '{ "searchQueries": ["bittensor"], "maxResults": 10, "includeSubtitles": true }' ``` ### Limits, privacy, and compliance - This Actor extracts public YouTube data only. - It does not scrape YouTube dislikes or private data. - Private, removed, age-restricted, geo-blocked, and rate-limited videos are reported with diagnostics where detectable. - Comments may contain personal data. Use comment extraction only when you have a lawful basis and a legitimate reason to process the data. - YouTube can change public pages and metadata without notice. The Actor includes diagnostics to make failures visible and easier to monitor. ### Troubleshooting | Symptom | What to try | | --- | --- | | No subtitles returned | Check `subtitles[]`, `subtitleErrorCode`, and language filters. Try `languages: ["en.*", ".*"]` if multilingual captions are acceptable. | | Search returns fewer rows than expected | Increase `maxResults`, loosen filters, or remove strict flags such as `is4K`, `isHDR`, or `hasLocation`. | | Comments are slow | Lower `maxCommentsPerVideo`, use `commentSort: "top"`, or run comments only on a filtered video set. | | Trending redirects | Check `searchDiagnostics.trendingFallbackUrl`; the Actor records the fallback search URL when YouTube redirects public Trending. | # Actor input Schema ## `startUrls` (type: `array`): Video, Shorts, channel, handle, playlist, or YouTube search-result URLs. ## `searchQueries` (type: `array`): YouTube search terms. Use maxResults/maxResultsShorts/maxResultStreams to control output buckets. ## `keywords` (type: `array`): Alias for searchQueries. ## `youtubeHandles` (type: `array`): YouTube handles or channel IDs. Examples: @bittensor, kurzgesagt, UC... ## `getTrending` (type: `boolean`): Scrape YouTube Trending for the selected gl/hl locale. ## `gl` (type: `string`): YouTube gl locale parameter such as US, GB, DE, or JP. ## `hl` (type: `string`): YouTube hl language parameter such as en, de, es, or ja. ## `maxItems` (type: `integer`): Total output cap across all sources. If maxResults is omitted, this also sets the per-source regular-video target. ## `maxResults` (type: `integer`): Maximum regular videos to emit per source. ## `maxResultsShorts` (type: `integer`): Maximum Shorts videos to emit per source. Use 0 to exclude Shorts. ## `maxResultStreams` (type: `integer`): Maximum livestream or stream replay videos to emit per source. Use 0 to exclude streams. ## `sortBy` (type: `string`): Sorting order. Also accepts the sortingOrder alias with relevance, rating, date, or views. ## `sortingOrder` (type: `string`): Alias for sortBy. ## `sort` (type: `string`): Search sort alias. Supports r/relevance, date, views, and rating. ## `dateFilter` (type: `string`): Relative or custom upload date filter applied after extraction, and mapped into search URLs where supported. ## `uploadDate` (type: `string`): Upload date alias: all, hour, today, week, month, or year. ## `dateAfter` (type: `string`): YYYY-MM-DD. Used when dateFilter is custom. ## `dateBefore` (type: `string`): YYYY-MM-DD. Used when dateFilter is custom. ## `videoType` (type: `string`): Search-compatible type filter. Movie matching is best-effort from public metadata. ## `features` (type: `string`): Single feature or comma-separated features: any, 4k, hd, live, movie, cc, 3d, hdr, location, purchased, subtitles, vr180, vr360. ## `lengthFilter` (type: `string`): Search-compatible length filter. ## `duration` (type: `string`): Duration alias. Maps short to under4, medium to between420, and long to plus20. ## `isHD` (type: `boolean`): Only include HD videos when true, or exclude HD videos when false. ## `hasSubtitles` (type: `boolean`): Only include videos with public subtitle tracks when true. ## `hasCC` (type: `boolean`): Only include videos marked with a Creative Commons license when true. ## `is3D` (type: `boolean`): Only include videos with public 3D signals when true. ## `isLive` (type: `boolean`): Only include live or stream replay results when true. ## `isBought` (type: `boolean`): Compatibility-only purchased/premium filter. Public unauthenticated YouTube often returns no real video rows for this filter, and purchase availability is not reliably exposed. ## `is4K` (type: `boolean`): Only include videos with 4K public formats when true. ## `is360` (type: `boolean`): Only include videos with 360-degree public metadata when true. ## `hasLocation` (type: `boolean`): Only include videos with public location metadata when true. ## `isHDR` (type: `boolean`): Only include videos with HDR public format metadata when true. ## `isVR180` (type: `boolean`): Only include videos with VR180 public metadata when true. ## `oldestPostDate` (type: `string`): YYYY-MM-DD or relative values such as 1 day, 7 days. ## `sortVideosBy` (type: `string`): Post-sorts extracted channel/search candidates by newest, popular, or oldest. ## `enrichChannelAbout` (type: `boolean`): Fetch channel about pages once per channel to fill description, links, subscriber count, total videos, and total views where public. ## `includeSubtitles` (type: `boolean`): Extract public manual captions first and auto-generated captions second. ## `downloadSubtitles` (type: `boolean`): Alias for includeSubtitles. ## `saveSubsToKVS` (type: `boolean`): Compatibility alias. Defaults to true in this actor so downstream automations can use stable KV URLs. ## `languages` (type: `array`): Language codes or regex patterns, tried in order. Example: en.\*,es,fr. ## `subtitlesLanguage` (type: `string`): Compatibility alias. Use any, en, de, es, fr, it, ja, ko, nl, pt, or ru. ## `preferAutoGeneratedSubtitles` (type: `boolean`): Prefer auto-generated captions before manual captions. ## `subtitlesFormat` (type: `string`): Choose one subtitle payload format or keep all AI-ready formats. ## `includeComments` (type: `boolean`): Fetch comments with yt-dlp. Large values can significantly increase runtime. ## `commentSort` (type: `string`): Comment sorting mode passed to yt-dlp when comments are enabled. ## `maxCommentsPerVideo` (type: `integer`): Maximum comments to extract per video when includeComments is enabled. ## `transcriptMode` (type: `string`): Use captions only, or fall back to Whisper when no suitable caption track exists. ## `openaiApiKey` (type: `string`): Secret. Required only for captionsThenWhisper. ## `maxWhisperMinutesPerRun` (type: `integer`): Total audio minutes allowed for Whisper fallback in one actor run. ## `maxAudioDurationMinutes` (type: `integer`): Maximum individual video duration eligible for Whisper fallback. ## `enableDedup` (type: `boolean`): Skip previously emitted videos per source until they age beyond the refresh window. ## `refreshWindowDays` (type: `integer`): Recently seen videos older than this many days are refreshed so mutable metrics stay current. ## `customMapFunction` (type: `string`): JavaScript function. Receives each output row as item/input and should return JSON-serializable data. ## `proxyConfiguration` (type: `object`): Apify proxy configuration. Plain Apify Proxy is the default; switch to residential for tougher runs. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.youtube.com/@bittensor/videos" } ], "searchQueries": [ "bittensor", "bitcoin" ], "getTrending": false, "gl": "us", "hl": "en", "maxResults": 50, "maxResultsShorts": 0, "maxResultStreams": 0, "sortBy": "relevance", "dateFilter": "any", "videoType": "any", "lengthFilter": "any", "sortVideosBy": "NEWEST", "enrichChannelAbout": true, "includeSubtitles": true, "saveSubsToKVS": true, "languages": [ "en.*" ], "preferAutoGeneratedSubtitles": false, "subtitlesFormat": "all", "includeComments": false, "commentSort": "top", "maxCommentsPerVideo": 500, "transcriptMode": "captionsOnly", "maxWhisperMinutesPerRun": 60, "maxAudioDurationMinutes": 20, "enableDedup": true, "refreshWindowDays": 7, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `results` (type: `string`): No description ## `summary` (type: `string`): No description ## `sourceDiagnostics` (type: `string`): No description ## `subtitleFiles` (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/@bittensor/videos" } ], "searchQueries": [ "bittensor", "bitcoin" ] }; // Run the Actor and wait for it to finish const run = await client.actor("crowdpull/youtube-scraper-intelligence").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/@bittensor/videos" }], "searchQueries": [ "bittensor", "bitcoin", ], } # Run the Actor and wait for it to finish run = client.actor("crowdpull/youtube-scraper-intelligence").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/@bittensor/videos" } ], "searchQueries": [ "bittensor", "bitcoin" ] }' | apify call crowdpull/youtube-scraper-intelligence --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crowdpull/youtube-scraper-intelligence", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Scraper Intelligence", "description": "Scrape public YouTube videos, Shorts, streams, channels, playlists, search results, subtitles, comments, and AI-ready transcript records.", "version": "0.1", "x-build-id": "4puLKxfZZOEw0Jv30" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crowdpull~youtube-scraper-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crowdpull-youtube-scraper-intelligence", "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/crowdpull~youtube-scraper-intelligence/runs": { "post": { "operationId": "runs-sync-crowdpull-youtube-scraper-intelligence", "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/crowdpull~youtube-scraper-intelligence/run-sync": { "post": { "operationId": "run-sync-crowdpull-youtube-scraper-intelligence", "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": "Video, Shorts, channel, handle, playlist, or YouTube search-result URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "Search queries", "type": "array", "description": "YouTube search terms. Use maxResults/maxResultsShorts/maxResultStreams to control output buckets.", "items": { "type": "string" } }, "keywords": { "title": "Search keywords alias", "type": "array", "description": "Alias for searchQueries.", "items": { "type": "string" } }, "youtubeHandles": { "title": "YouTube handles/channels", "type": "array", "description": "YouTube handles or channel IDs. Examples: @bittensor, kurzgesagt, UC...", "items": { "type": "string" } }, "getTrending": { "title": "Get trending videos", "type": "boolean", "description": "Scrape YouTube Trending for the selected gl/hl locale.", "default": false }, "gl": { "title": "Search country", "type": "string", "description": "YouTube gl locale parameter such as US, GB, DE, or JP.", "default": "us" }, "hl": { "title": "Search language", "type": "string", "description": "YouTube hl language parameter such as en, de, es, or ja.", "default": "en" }, "maxItems": { "title": "Maximum total items", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Total output cap across all sources. If maxResults is omitted, this also sets the per-source regular-video target." }, "maxResults": { "title": "Max regular videos per source", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum regular videos to emit per source.", "default": 50 }, "maxResultsShorts": { "title": "Max Shorts per source", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum Shorts videos to emit per source. Use 0 to exclude Shorts.", "default": 0 }, "maxResultStreams": { "title": "Max streams per source", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum livestream or stream replay videos to emit per source. Use 0 to exclude streams.", "default": 0 }, "sortBy": { "title": "Sorting order", "enum": [ "relevance", "uploadDate", "viewCount", "rating" ], "type": "string", "description": "Sorting order. Also accepts the sortingOrder alias with relevance, rating, date, or views.", "default": "relevance" }, "sortingOrder": { "title": "Sorting order alias", "enum": [ "relevance", "rating", "date", "views" ], "type": "string", "description": "Alias for sortBy." }, "sort": { "title": "Sort alias", "type": "string", "description": "Search sort alias. Supports r/relevance, date, views, and rating." }, "dateFilter": { "title": "Date filter", "enum": [ "any", "hour", "day", "week", "month", "year", "custom" ], "type": "string", "description": "Relative or custom upload date filter applied after extraction, and mapped into search URLs where supported.", "default": "any" }, "uploadDate": { "title": "Upload date alias", "enum": [ "all", "any", "hour", "today", "day", "week", "month", "year" ], "type": "string", "description": "Upload date alias: all, hour, today, week, month, or year." }, "dateAfter": { "title": "Date after", "type": "string", "description": "YYYY-MM-DD. Used when dateFilter is custom." }, "dateBefore": { "title": "Date before", "type": "string", "description": "YYYY-MM-DD. Used when dateFilter is custom." }, "videoType": { "title": "Video type filter", "enum": [ "any", "video", "movie" ], "type": "string", "description": "Search-compatible type filter. Movie matching is best-effort from public metadata.", "default": "any" }, "features": { "title": "Feature filter", "type": "string", "description": "Single feature or comma-separated features: any, 4k, hd, live, movie, cc, 3d, hdr, location, purchased, subtitles, vr180, vr360." }, "lengthFilter": { "title": "Length filter", "enum": [ "any", "under4", "between420", "plus20" ], "type": "string", "description": "Search-compatible length filter.", "default": "any" }, "duration": { "title": "Duration alias", "enum": [ "all", "any", "short", "medium", "long" ], "type": "string", "description": "Duration alias. Maps short to under4, medium to between420, and long to plus20." }, "isHD": { "title": "HD", "type": "boolean", "description": "Only include HD videos when true, or exclude HD videos when false." }, "hasSubtitles": { "title": "Subtitles/CC", "type": "boolean", "description": "Only include videos with public subtitle tracks when true." }, "hasCC": { "title": "Creative Commons", "type": "boolean", "description": "Only include videos marked with a Creative Commons license when true." }, "is3D": { "title": "3D", "type": "boolean", "description": "Only include videos with public 3D signals when true." }, "isLive": { "title": "Live", "type": "boolean", "description": "Only include live or stream replay results when true." }, "isBought": { "title": "Purchased", "type": "boolean", "description": "Compatibility-only purchased/premium filter. Public unauthenticated YouTube often returns no real video rows for this filter, and purchase availability is not reliably exposed." }, "is4K": { "title": "4K", "type": "boolean", "description": "Only include videos with 4K public formats when true." }, "is360": { "title": "360 degrees", "type": "boolean", "description": "Only include videos with 360-degree public metadata when true." }, "hasLocation": { "title": "Location", "type": "boolean", "description": "Only include videos with public location metadata when true." }, "isHDR": { "title": "HDR", "type": "boolean", "description": "Only include videos with HDR public format metadata when true." }, "isVR180": { "title": "VR180", "type": "boolean", "description": "Only include videos with VR180 public metadata when true." }, "oldestPostDate": { "title": "Scrape videos published after date", "type": "string", "description": "YYYY-MM-DD or relative values such as 1 day, 7 days." }, "sortVideosBy": { "title": "Sort channel videos by", "enum": [ "NEWEST", "POPULAR", "OLDEST" ], "type": "string", "description": "Post-sorts extracted channel/search candidates by newest, popular, or oldest.", "default": "NEWEST" }, "enrichChannelAbout": { "title": "Enrich channel/about fields", "type": "boolean", "description": "Fetch channel about pages once per channel to fill description, links, subscriber count, total videos, and total views where public.", "default": true }, "includeSubtitles": { "title": "Include subtitles", "type": "boolean", "description": "Extract public manual captions first and auto-generated captions second.", "default": true }, "downloadSubtitles": { "title": "Download subtitles alias", "type": "boolean", "description": "Alias for includeSubtitles." }, "saveSubsToKVS": { "title": "Save subtitles to key-value store", "type": "boolean", "description": "Compatibility alias. Defaults to true in this actor so downstream automations can use stable KV URLs.", "default": true }, "languages": { "title": "Subtitle language fallback", "type": "array", "description": "Language codes or regex patterns, tried in order. Example: en.*,es,fr.", "default": [ "en.*" ], "items": { "type": "string" } }, "subtitlesLanguage": { "title": "Subtitle language alias", "type": "string", "description": "Compatibility alias. Use any, en, de, es, fr, it, ja, ko, nl, pt, or ru." }, "preferAutoGeneratedSubtitles": { "title": "Prefer auto-generated subtitles", "type": "boolean", "description": "Prefer auto-generated captions before manual captions.", "default": false }, "subtitlesFormat": { "title": "Subtitle format", "enum": [ "all", "srt", "vtt", "xml", "plaintext" ], "type": "string", "description": "Choose one subtitle payload format or keep all AI-ready formats.", "default": "all" }, "includeComments": { "title": "Include full comments", "type": "boolean", "description": "Fetch comments with yt-dlp. Large values can significantly increase runtime.", "default": false }, "commentSort": { "title": "Comment sort", "enum": [ "top", "new" ], "type": "string", "description": "Comment sorting mode passed to yt-dlp when comments are enabled.", "default": "top" }, "maxCommentsPerVideo": { "title": "Max comments per video", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Maximum comments to extract per video when includeComments is enabled.", "default": 500 }, "transcriptMode": { "title": "Transcript mode", "enum": [ "captionsOnly", "captionsThenWhisper" ], "type": "string", "description": "Use captions only, or fall back to Whisper when no suitable caption track exists.", "default": "captionsOnly" }, "openaiApiKey": { "title": "OpenAI API key", "type": "string", "description": "Secret. Required only for captionsThenWhisper." }, "maxWhisperMinutesPerRun": { "title": "Max Whisper minutes per run", "minimum": 0, "maximum": 1440, "type": "integer", "description": "Total audio minutes allowed for Whisper fallback in one actor run.", "default": 60 }, "maxAudioDurationMinutes": { "title": "Max audio duration per video", "minimum": 1, "maximum": 720, "type": "integer", "description": "Maximum individual video duration eligible for Whisper fallback.", "default": 20 }, "enableDedup": { "title": "Enable Smart Scrape dedup", "type": "boolean", "description": "Skip previously emitted videos per source until they age beyond the refresh window.", "default": true }, "refreshWindowDays": { "title": "Refresh window days", "minimum": 0, "maximum": 365, "type": "integer", "description": "Recently seen videos older than this many days are refreshed so mutable metrics stay current.", "default": 7 }, "customMapFunction": { "title": "Custom map function", "type": "string", "description": "JavaScript function. Receives each output row as item/input and should return JSON-serializable data." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy configuration. Plain Apify Proxy is the default; switch to residential for tougher runs.", "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 } } } } } } } } } } ```