# YouTube Music Video Scraper (`w3crawler/youtube-music-video-scraper`) Actor Search and browse YouTube Music videos with first-party YouTube Music endpoints, pagination, deduplication, and optional player metadata. - **URL**: https://apify.com/w3crawler/youtube-music-video-scraper.md - **Developed by:** [w3crawler](https://apify.com/w3crawler) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.99 / 1,000 music videos This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ### What this Actor does YouTube Music Video Scraper collects deduplicated public music-video results from [YouTube](https://www.youtube.com/) search pages and public [YouTube Music](https://music.youtube.com/) or YouTube playlist, browse, and channel pages. It records the public title, artist/channel context, album text when exposed, duration, displayed counts, thumbnails, canonical links, source rank, and extraction provenance. The Actor requests ordinary public rendered HTML and parses embedded page data. Optional player enrichment reads the public watch page for a description, dates, keywords, caption-language summaries, playability status, and audio/video format counts. It never stores signed caption or media URLs and does not download media. Typical uses include music-video discovery, artist or album research, public playlist inventory, chart-like snapshots, deduplicated candidate lists for editorial workflows, and point-in-time metadata exports. ### Supported targets and boundaries - Search target: public YouTube results for music-video phrases. - Start targets: public YouTube or YouTube Music playlist, browse, and channel URLs. - When both input arrays are supplied, `startUrls` are processed first. All sources share one run-wide `maxItems` cap. - The source order is the public page order. The Actor does not claim an official chart ranking or stable historical counts. - The implementation uses public HTML and embedded `ytInitialData` / `ytInitialPlayerResponse` only. It does not call private YouTube Music endpoints, alternate clients, hidden APIs, login-only pages, or media endpoints. ### Input Provide at least one non-empty `searchQueries` or `startUrls` entry. The runtime trims and deduplicates both arrays before processing. | Field | Type and default | Description | | ---------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `searchQueries` | string array; no default; max 100 | Public keyword phrases. Each trimmed phrase is 1–200 characters. Search sources run after all `startUrls`. | | `startUrls` | string array; no default; max 100 | HTTPS YouTube/YouTube Music playlist, browse, or channel URLs. Each start URL uses one public page and runs before search sources. | | `maxItems` | integer; `20`; 1–100 | Maximum unique video rows across every source combined. Deduplication is by `videoId`. | | `maxPages` | integer; `3`; 1–10 | Maximum public search-page requests per search query. Start URLs always use one page. | | `maxRetries` | integer; `1`; 0–3 | Retries the same public request with bounded backoff and the same transport context. | | `requestTimeoutSecs` | integer; `60`; 15–180 | Timeout for each public result-page or watch-page request. | | `requestDelayMs` | integer; `250`; 0–5000 | Delay between successive public search pages. It does not add pagination to start URLs or player requests. | | `countryCode` | string; `US` | Two-letter country context, normalized to uppercase, such as `US`, `GB`, or `IN`. | | `languageCode` | string; `en` | Language context, normalized to lowercase, such as `en`, `es`, or `pt-BR`. | | `includePlayerDetails` | boolean; `true` | Fetch one public watch page per retained video and attach bounded metadata when available. | | `enableProxyFallback` | boolean; `true` | After a direct request fails, allow one request through the configured Apify Proxy. This is fallback behavior, not access-control bypass. | | `includeDiagnostics` | boolean; `true` | Retain page and optional-enrichment diagnostics. Each diagnostic has exactly `url`, `error`, `errorCode`, and `scrapedAt`. | | `proxyConfiguration` | object; none | Optional account-authorized Apify Proxy configuration or credential-free HTTP/SOCKS URLs. Credentials and proxy URLs are never written to output. | The runtime rejects unknown input fields, invalid URLs, proxy credentials, unsupported proxy fields, unsafe proxy protocols, and values outside the ranges above. #### Minimal search input ```json { "searchQueries": ["Adele official music video"], "maxItems": 10 } ``` #### Known public playlist input ```json { "startUrls": [ "https://www.youtube.com/playlist?list=PL2JtvykrieUxaLXkeuXRHb-pJB9XpVWtd" ], "maxItems": 10, "includePlayerDetails": false } ``` #### Combined sources with bounded options ```json { "startUrls": [ "https://music.youtube.com/playlist?list=PL2JtvykrieUxaLXkeuXRHb-pJB9XpVWtd" ], "searchQueries": ["Adele live music video"], "maxItems": 20, "maxPages": 2, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includePlayerDetails": true, "enableProxyFallback": true, "includeDiagnostics": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` ### Run it in Apify Console 1. Open the Actor and click **Start**. 2. In **Input**, paste one of the JSON examples above or enter the fields in the form. 3. Confirm the public source URLs, `maxItems`, and whether optional player enrichment is needed. 4. Click **Start** and wait for the run to finish. 5. Open the **Dataset** for result rows and the `OUTPUT` key in the run’s key-value store for counts and diagnostics; export the dataset as needed. ### Output records #### Rich normal record This is a representative source-shaped record. Optional values are omitted when the public page does not expose them. ```json { "recordType": "youtube_music_video", "videoId": "dQw4w9WgXcQ", "title": "Adele - Rolling in the Deep", "description": "Official music video", "descriptionLength": 20, "accessibilityText": "Adele - Rolling in the Deep 4 minutes, 03 seconds", "artists": [ { "name": "Adele", "id": "UCsRM0YB_dabtEPGPTKo-gcw", "url": "https://www.youtube.com/channel/UCsRM0YB_dabtEPGPTKo-gcw" } ], "artist": "Adele", "album": "21", "duration": "4:03", "durationSeconds": 243, "views": 1200000000, "viewsText": "1.2B views", "releaseYear": 2011, "publishedTimeText": "13 years ago", "explicit": false, "badges": ["Official"], "thumbnails": [ { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg", "width": 720, "height": 404 } ], "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg", "thumbnailCount": 1, "channelName": "Adele", "channelId": "UCsRM0YB_dabtEPGPTKo-gcw", "channelUrl": "https://www.youtube.com/channel/UCsRM0YB_dabtEPGPTKo-gcw", "youtubeMusicUrl": "https://music.youtube.com/watch?v=dQw4w9WgXcQ", "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "source": "search", "searchQuery": "Adele official music video", "sourceUrl": "https://www.youtube.com/results?search_query=Adele+official+music+video&hl=en&gl=US&sp=EgIQAQ%3D%3D", "rank": 1, "sourceRank": 1, "searchRank": 1, "page": 1, "resultSource": "ytInitialData.videoRenderer", "sourceTransport": "public-rendered-html-direct", "extractionMethod": "youtube-public-page-embedded-initial-data", "metadataSource": "youtube-public-search-page", "metadataEnriched": true, "isShort": false, "isLive": false, "isUpcoming": false, "continuationDetected": true, "continuationCount": 1, "initialItemsExposed": 20, "requestedMaxItems": 10, "languageCode": "en", "countryCode": "US", "playerDetailsRequested": true, "playerDetailsAvailable": true, "playerDetailsStatus": "available", "playerTransport": "youtube-public-watch-page", "player": { "title": "Adele - Rolling in the Deep", "description": "Official music video", "descriptionLength": 20, "durationSeconds": 243, "viewCount": 1200000000, "channelName": "Adele", "channelId": "UCsRM0YB_dabtEPGPTKo-gcw", "channelUrl": "https://www.youtube.com/channel/UCsRM0YB_dabtEPGPTKo-gcw", "isLive": false, "keywords": ["Adele", "music"], "publishDate": "2011-01-24", "uploadDate": "2011-01-24", "category": "Music", "tags": ["Adele", "Rolling in the Deep"], "captions": [ { "languageCode": "en", "name": "English", "kind": "asr", "isAutoGenerated": true, "isTranslatable": true } ], "captionCount": 1, "playabilityStatus": "OK", "hasVideo": true, "hasAudio": true, "formatCount": 34, "videoFormatCount": 20, "audioFormatCount": 14, "metadataSource": "youtube-public-watch-page", "extractionMethod": "youtube-public-watch-page-embedded-player-response" }, "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` #### Fallback normal record and diagnostic If the source result is usable but its optional watch page is unavailable, the normal row is retained with `playerDetailsStatus: "unavailable"`; the separate diagnostic explains the omission. ```json { "recordType": "youtube_music_video", "videoId": "9bZkp7q19f0", "title": "Public music-video result", "youtubeMusicUrl": "https://music.youtube.com/watch?v=9bZkp7q19f0", "youtubeUrl": "https://www.youtube.com/watch?v=9bZkp7q19f0", "source": "search", "sourceUrl": "https://www.youtube.com/results?search_query=music&hl=en&gl=US&sp=EgIQAQ%3D%3D", "rank": 1, "sourceRank": 1, "searchRank": 1, "page": 1, "resultSource": "ytInitialData.videoRenderer", "sourceTransport": "public-rendered-html-via-apify-proxy", "extractionMethod": "youtube-public-page-embedded-initial-data", "metadataSource": "youtube-public-search-page", "metadataEnriched": true, "continuationDetected": false, "continuationCount": 0, "initialItemsExposed": 1, "requestedMaxItems": 1, "languageCode": "en", "countryCode": "US", "playerDetailsRequested": true, "playerDetailsAvailable": false, "playerDetailsStatus": "unavailable", "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` ```json { "url": "https://www.youtube.com/watch?v=9bZkp7q19f0", "error": "Public YouTube watch page did not expose matching player metadata", "errorCode": "PLAYER_METADATA_UNAVAILABLE", "scrapedAt": "2026-09-08T12:00:00.001Z" } ``` #### `OUTPUT` run summary The Actor writes this JSON object under the `OUTPUT` key in the default key-value store. ```json { "runType": "youtube-public-music-video-run", "status": "success", "dataAvailable": true, "sourceCount": 2, "sourcesWithItems": 2, "maxItems": 20, "maxPages": 3, "pagesFetched": 2, "pageAttempts": 4, "itemCount": 2, "diagnosticCount": 0, "failedCount": 0, "blockedCount": 0, "playerDetailsRequested": 2, "playerDetailsAvailableCount": 2, "playerDetailsUnavailableCount": 0, "continuationDetected": true, "continuationCount": 1, "proxyRequested": false, "proxyConfigured": false, "includeDiagnostics": true, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestDelayMs": 250, "requestTimeoutSecs": 60, "paginationMethod": "public-page-query", "extractionMethod": "youtube-public-page-embedded-initial-data", "durationMs": 4661, "finishedAt": "2026-09-08T12:00:04.661Z" } ``` ### Field reference and semantics | Group | Fields | Semantics | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Identity | `recordType`, `videoId`, `title`, `description`, `descriptionLength`, `accessibilityText` | Identity and text are copied or parsed from public result/watch metadata. Missing values are omitted. | | Music context | `artists[]`, `artist`, `album`, `duration`, `durationSeconds` | Artist/channel links and album text are present only when exposed by the renderer. `durationSeconds` is parsed from a public duration string. | | Public stats | `views`, `viewsText`, `releaseYear`, `publishedTimeText`, `explicit`, `badges` | `views` is a parsed count; `viewsText` preserves the displayed text. These are point-in-time observations. | | Channel and images | `channelName`, `channelId`, `channelUrl`, `thumbnails[]`, `thumbnailUrl`, `thumbnailCount` | URLs are restricted to public YouTube/Google image hosts and are not signed media URLs. | | Canonical links | `youtubeUrl`, `youtubeMusicUrl` | Both are derived from the validated 11-character `videoId`. | | Source and rank | `source`, `searchQuery`, `sourceUrl`, `rank`, `sourceRank`, `searchRank`, `page`, `resultSource` | `rank` is run order after deduplication. `sourceRank` is order among unique rows from the source; `searchRank` is present for search sources. | | Provenance | `sourceTransport`, `extractionMethod`, `metadataSource`, `metadataEnriched`, `scrapedAt` | Identifies the public page family, transport, parser, and emission time. | | Flags and limits | `isShort`, `isLive`, `isUpcoming`, `continuationDetected`, `continuationCount`, `initialItemsExposed`, `requestedMaxItems`, `languageCode`, `countryCode` | Records flags and the bounded request context visible for that row. Continuation markers are observed, not followed. | | Player status | `playerDetailsRequested`, `playerDetailsAvailable`, `playerDetailsStatus`, `playerTransport`, `player` | Optional public watch-page enrichment. `player` contains metadata, caption-language summaries, and format counts only. | | Diagnostics | `url`, `error`, `errorCode`, `scrapedAt` | Diagnostic rows have exactly these four fields and never masquerade as normal results. | Nested `artists` entries contain `name`, `id`, and `url`. Nested `thumbnails` entries contain `url`, `width`, and `height`. Nested `player` fields include title/description, dates, keywords/tags, `captions` language summaries, playability, and format counts. Caption and media URLs are deliberately omitted. ### Pagination, deduplication, and omissions - Search pagination uses the ordinary public `page` query parameter up to `maxPages` for each query. Start URLs use one public page. - The Actor reports embedded continuation markers in `continuationDetected` and `continuationCount` but does not replay private continuation requests. - Rows are deduplicated by `videoId`; the first occurrence in start-URL-then-search source order is retained. `maxItems` is a run-wide cap. - There are no user-configurable filters or sorts beyond the built-in music-video search filter and the source page’s own order. The Actor does not fabricate ranking, artist, album, price, date, or availability values. - Player enrichment is one bounded public watch-page request per retained video when `includePlayerDetails` is true. It does not expand `maxPages`. - Missing public fields are omitted. An empty result page, blocked page, or failed public request increments the relevant summary count and emits a diagnostic when enabled. A usable result with unavailable player enrichment remains a normal row with the player fields omitted. - Output never includes cookies, authorization headers, proxy credentials/URLs, request identities, fingerprint data, private client parameters, signed caption URLs, streaming URLs, playback URLs, or downloaded media. ### Proxy behavior and cost Direct public HTML is attempted first unless an explicit proxy configuration is supplied. With `enableProxyFallback`, a failed direct request may be retried once through the configured account-authorized Apify Proxy. A proxy is not a guarantee of access and is not used to bypass CAPTCHAs, authentication, or access controls. `sourceTransport` and `OUTPUT.proxyConfigured` state what happened without exposing proxy details. Actor cost is driven by Apify compute time and memory, plus any proxy traffic used by your account; the Actor does not add a fixed per-result charge. Actual cost depends on the selected plan, run duration, page count, player enrichment, and proxy use. Check the current [Apify pricing](https://apify.com/pricing) and the run’s resource usage for the authoritative amount. ### Troubleshooting #### The run returns diagnostics and no rows Confirm that at least one URL is a public HTTPS YouTube/YouTube Music playlist, browse, or channel page, or try a broader public search phrase. Review `OUTPUT.status`, `failedCount`, `blockedCount`, and the diagnostic `errorCode`. A public page can change shape or be temporarily unavailable. #### Search rows are present but player metadata is missing Set `includePlayerDetails` to `false` when only search-page metadata is needed, or leave it enabled and treat `playerDetailsStatus: "unavailable"` as an honest fallback. The Actor does not substitute private endpoints or signed URLs. #### Results are fewer than `maxItems` `maxItems` is a maximum, not a promise. The public page may expose fewer music-video candidates, duplicates may be removed, a source may be blocked, or continuation markers may be visible without being followed. Use more distinct queries or public start URLs within the input limits. #### Proxy fallback is not used Fallback requires `enableProxyFallback: true` and a proxy configuration that can resolve in the current Apify account. Explicit proxy mode uses that configuration for the request. Credential-bearing proxy URLs are rejected. ### API and support The Actor’s Console **API** tab exposes the current run, dataset, and key-value store links. For programmatic access, use the [Apify API documentation](https://docs.apify.com/api/v2) and read the default dataset plus the `OUTPUT` key from the run’s default key-value store. Use the Actor’s Console **Issues** or support channel to report a reproducible public URL, input, run ID, and diagnostic code; do not include secrets or proxy credentials. ### Privacy, legal, and non-affiliation Use this Actor only for public pages and in accordance with YouTube’s Terms of Service, applicable law, and any site-specific rules. You are responsible for choosing lawful targets, respecting rights and rate limits, and assessing whether an export contains personal information. The Actor does not log in, access private content, bypass CAPTCHAs, or evade access controls. It stores public metadata and bounded diagnostics in the run’s Apify dataset and key-value store; it does not intentionally store cookies, credentials, signed media URLs, or downloaded media. This Actor is an independent community tool and is not affiliated with, endorsed by, or sponsored by YouTube, Google, or YouTube Music. Names and trademarks belong to their respective owners. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. # Changelog This Actor's version history is a separate document: https://apify.com/w3crawler/youtube-music-video-scraper/changelog.md # Actor input Schema ## `searchQueries` (type: `array`): Public YouTube keyword phrases. At least one searchQueries or startUrls entry is required. When both are supplied, startUrls are processed first and all sources share the maxItems cap. ## `startUrls` (type: `array`): Public YouTube or YouTube Music playlist, browse, or channel URLs. They are processed before searchQueries when both are supplied, and each start URL uses one public page. ## `maxItems` (type: `integer`): Maximum unique public video rows retained across all start URLs and search queries combined. ## `maxPages` (type: `integer`): Maximum number of public search-page requests per search query, from 1 to 10. Start URLs use one public page and embedded continuation markers are reported but not followed. ## `maxRetries` (type: `integer`): Retries the same public request with the same direct or configured-proxy transport context. ## `requestTimeoutSecs` (type: `integer`): Timeout in seconds for each public page attempt. ## `requestDelayMs` (type: `integer`): Bounded delay between successive public search-page requests. Start-page and watch-page requests are not paginated by this setting. ## `countryCode` (type: `string`): Two-letter locale context, for example US, GB, or IN. ## `languageCode` (type: `string`): Language context, such as en, es, or pt-BR. ## `includePlayerDetails` (type: `boolean`): Enrich each result from the public watch page with descriptions, dates, caption-language summaries, and format counts; signed caption/media URLs are never stored. Unavailable enrichment is recorded as a diagnostic when diagnostics are enabled. ## `enableProxyFallback` (type: `boolean`): After a direct public-page or watch-page failure, try one ordinary request through the configured Apify Proxy. This is a fallback only; it does not bypass authentication, CAPTCHAs, or access controls. ## `includeDiagnostics` (type: `boolean`): Write bounded page/player diagnostics with exactly url, error, errorCode, and scrapedAt. ## `proxyConfiguration` (type: `object`): Optional account-authorized Apify Proxy or credential-free HTTP/SOCKS URLs. ## Actor input object example ```json { "searchQueries": [ "Adele official music video" ], "maxItems": 20, "maxPages": 3, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includePlayerDetails": true, "enableProxyFallback": true, "includeDiagnostics": true, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `keyValueStore` (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 = { "searchQueries": [ "Adele official music video" ], "maxItems": 20, "maxPages": 3, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includePlayerDetails": true, "enableProxyFallback": true, "includeDiagnostics": true, "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("w3crawler/youtube-music-video-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 = { "searchQueries": ["Adele official music video"], "maxItems": 20, "maxPages": 3, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includePlayerDetails": True, "enableProxyFallback": True, "includeDiagnostics": True, "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("w3crawler/youtube-music-video-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "Adele official music video" ], "maxItems": 20, "maxPages": 3, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includePlayerDetails": true, "enableProxyFallback": true, "includeDiagnostics": true, "proxyConfiguration": { "useApifyProxy": false } }' | apify call w3crawler/youtube-music-video-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/youtube-music-video-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/NonzDma1nC5GCdhMY/builds/1q62tk3hOSEDm3gkz/openapi.json