# YouTube Music Albums Scraper (`w3crawler/youtube-music-albums-scraper`) Actor Search current YouTube Music album results and retrieve rich album and optional track metadata through YouTube Music's first-party youtubei endpoints. - **URL**: https://apify.com/w3crawler/youtube-music-albums-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 albums 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 Extract album-style public YouTube playlists and public YouTube Music album pages into bounded, source-backed records. The Actor uses the public HTML page and embedded initial page data; it does not call private YouTube request protocols. ### What this Actor does This Actor is useful for: - Building a public album and playlist catalog for music discovery. - Collecting playlist owners, artwork, descriptions, track lists, view text, and public URLs. - Comparing search-discovered album-style playlists with known public playlist URLs. - Auditing public-page availability with small, explicit diagnostic records. The source page is [YouTube](https://www.youtube.com/), and the public Music destination is [YouTube Music](https://music.youtube.com/). A search result or playlist is not treated as an official album merely because its title contains the word “album”. Only explicit public evidence is classified as `official_album`: a Music album identifier, an album content type, or an unambiguous album metadata label. Ordinary `PL...` playlists and direct playlist URLs are classified as `user_playlist` with `albumType: "Playlist"`. A year is populated only from release/date metadata associated with an official album. A year-looking title value is retained as `titleYearHint` and is never promoted to `releaseYear`. ### Input Provide at least one `searchQueries` entry or one public YouTube playlist URL in `startUrls`. Both may be supplied. Direct `startUrls` are processed first because they are deterministic detail targets; search queries run afterward until the global `maxItems` cap is reached. Duplicate queries are rejected case-insensitively, and duplicate playlist URLs are rejected after canonicalization. #### Input fields | Field | Type and limits | Behavior | | --------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `searchQueries` | string array, 0–25 items; each 1–200 characters | Optional public album, artist, or genre searches. | | `startUrls` | string array, 0–50 items | Optional `youtube.com/playlist?list=...` or `music.youtube.com/playlist?list=...` URLs. Credentials and non-YouTube hosts are rejected. | | `maxItems` | integer, 1–50; default `10` | Global cap on normal album records across both source types. | | `maxSearchItems` | integer, 1–50; defaults to `maxItems` at runtime | Maximum candidates considered per search query before the global cap. | | `maxStartItems` | integer, 1–50; defaults to `maxItems` at runtime | Maximum direct playlist URLs processed before the global cap. | | `maxPages` | integer, 1–3; default `1` | Recorded as a bounded page setting. The current public route fetches only each initial page and reports continuation markers without replaying continuation requests. | | `includeTracks` | boolean; default `true` | Include visible track rows from each successfully fetched detail page. | | `maxTracks` | integer, 0–200; default `50` | Maximum visible tracks retained per normal row. `0` keeps no track rows. | | `languageCode` | 2–3 letters; default `en` | Lowercase language context added to public URLs and request headers. | | `countryCode` | 2 letters; default `US` | Uppercase country context added to public URLs and request headers. | | `maxRetries` | integer, 0–3; default `1` | Bounded retries for a failed public page request. | | `requestTimeoutSecs` | integer, 15–180; default `60` | Timeout for one public HTML request. | | `requestDelayMs` | integer, 0–5000; default `250` | Delay between source page requests. | | `includeDiagnostics` | boolean; default `true` | Emit four-field diagnostics for blocked, empty, or failed public operations. | | `enableProxyFallback` | boolean; default `true` | After direct failure, try the configured Apify Proxy route when available. | | `proxyConfiguration` | Apify Proxy object; optional | Account-authorized proxy configuration. Proxy URLs must be credential-free. | #### Runnable input examples Minimal public search: ```json { "searchQueries": ["Adele album"] } ``` Known public playlist, with deterministic direct processing: ```json { "startUrls": [ "https://www.youtube.com/playlist?list=PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N" ], "maxItems": 1, "includeTracks": true, "maxTracks": 5, "enableProxyFallback": false } ``` Combined search, direct URL, limits, locale, diagnostics, and proxy fallback: ```json { "searchQueries": ["Adele album", "jazz album playlist"], "startUrls": [ "https://music.youtube.com/playlist?list=PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N" ], "maxItems": 3, "maxSearchItems": 2, "maxStartItems": 1, "maxPages": 1, "includeTracks": true, "maxTracks": 10, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestTimeoutSecs": 45, "requestDelayMs": 250, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } } ``` ### Run it in the Apify Console 1. Open the Actor and select the **Input** tab. 2. Paste one of the JSON objects above, or enter the fields in the form. 3. If a proxy route is needed, configure the account-authorized Apify Proxy options and leave proxy URLs credential-free. 4. Click **Start** and open the **Dataset** tab after the run finishes. 5. Open the `OUTPUT` key-value record to review counts, access state, limits, and duration. ### Output #### Normal album record Normal rows have `recordType: "youtube_music_album"`. This is a representative rich row; fields not exposed by the public page are omitted. ```json { "recordType": "youtube_music_album", "searchQuery": "Adele album", "browseId": "PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N", "title": "Adele - 30", "albumType": "Playlist", "isOfficialAlbum": false, "sourceKind": "user_playlist", "classificationEvidence": "direct_playlist_url", "artist": "Adele", "creatorName": "AdeleVEVO", "albumUrl": "https://www.youtube.com/playlist?list=PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N", "musicUrl": "https://music.youtube.com/playlist?list=PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N", "description": "The complete album playlist.", "descriptionLength": 29, "totalTrackCount": 12, "totalTrackCountText": "12 videos", "totalViewCount": 1234, "totalViewCountText": "1,234 views", "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "thumbnailCount": 1, "thumbnails": [ { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 480, "height": 360 } ], "trackCount": 1, "rawTrackCount": 1, "tracks": [ { "position": 1, "title": "Hello", "artist": "Adele", "channelName": "AdeleVEVO", "duration": "4:55", "durationSeconds": 295, "views": 1234567, "viewsText": "1.2M views", "publishedTimeText": "3 years ago", "videoId": "dQw4w9WgXcQ", "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "musicUrl": "https://music.youtube.com/watch?v=dQw4w9WgXcQ", "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "thumbnailCount": 1, "thumbnails": [ { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 480, "height": 360 } ], "sourceRenderer": "public-playlist-video-renderer" } ], "initialItemsExposed": 1, "continuationDetected": false, "continuationCount": 0, "source": "startUrl", "sourceUrl": "https://www.youtube.com/playlist?list=PLxgEqpZ1Pdg9qG-7bLycTPgINtzneUk_N", "rank": 1, "page": 1, "sourceRenderer": "public-start-url", "sourceTransport": "public-rendered-html-direct", "extractionMethod": "youtube-public-page-embedded-initial-data", "metadataSource": "youtube-public-playlist-page", "metadataEnriched": true, "albumPageAvailable": true, "requestedMaxItems": 1, "requestedMaxSearchItems": 1, "requestedMaxStartItems": 1, "requestedMaxPages": 1, "requestedMaxTracks": 5, "includeTracks": true, "languageCode": "en", "countryCode": "US", "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` #### Fallback and diagnostic record When direct public HTML fails and fallback is enabled, the Actor tries the configured Apify Proxy route. If the public page remains blocked, empty, or unparsable, it emits this exact four-field diagnostic shape when `includeDiagnostics` is `true`: ```json { "url": "https://www.youtube.com/results?search_query=Adele+album&hl=en&gl=US", "error": "Public YouTube page reported an access block.", "errorCode": "SEARCH_ACCESS_BLOCKED", "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` Diagnostics are not album records. The Actor does not fabricate titles, tracks, release dates, counts, or URLs when the source page does not expose them. #### `OUTPUT` summary The `OUTPUT` key-value record reconciles normal and diagnostic counts and records the actual public-page work performed: ```json { "runType": "youtube-public-music-albums-run", "status": "success", "dataAvailable": true, "sourceCount": 2, "sourcesWithItems": 2, "searchPagesFetched": 1, "albumPagesFetched": 2, "pageAttempts": 4, "itemCount": 2, "diagnosticCount": 0, "failedCount": 0, "blockedCount": 0, "continuationDetected": false, "continuationCount": 0, "proxyRequested": true, "proxyConfigured": true, "includeDiagnostics": true, "includeTracks": true, "maxItems": 2, "maxSearchItems": 1, "maxStartItems": 1, "maxPages": 1, "maxTracks": 5, "maxRetries": 1, "requestDelayMs": 250, "requestTimeoutSecs": 45, "languageCode": "en", "countryCode": "US", "paginationMethod": "bounded-public-search-page-no-continuation-calls", "extractionMethod": "youtube-public-page-embedded-initial-data", "durationMs": 2450, "finishedAt": "2026-09-08T12:00:00.000Z" } ``` You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. ### Field reference All normal fields are source-backed or run-provenance fields. Optional values are omitted when not exposed or not applicable. | Field | Meaning and source | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `recordType` | Normal-row discriminator, always `youtube_music_album` for a usable record. | | `searchQuery` | Search term that found the candidate; omitted for direct-only rows. | | `browseId` | Public playlist or Music album identifier. | | `title`, `albumType`, `contentType` | Visible title and source classification labels. | | `isOfficialAlbum`, `sourceKind`, `classificationEvidence` | Conservative official-album versus user-playlist classification and its public evidence. | | `artist`, `creatorName`, `creatorId`, `creatorUrl` | Artist/owner and public channel metadata, when exposed. | | `year`, `releaseYear`, `releaseDate`, `titleYearHint`, `releaseMetadataSource` | Release metadata and its provenance; title hints are kept separate. | | `albumUrl`, `musicUrl` | Public YouTube and YouTube Music destination URLs. | | `description`, `descriptionLength`, `releaseMetadata`, `updatedText` | Visible description and normalized public metadata/statistics text. | | `totalTrackCount`, `totalTrackCountText` | Source-reported playlist size. | | `totalViewCount`, `totalViewCountText` | Source-reported playlist views. | | `thumbnailUrl`, `thumbnailCount`, `thumbnails` | Public artwork URLs and source dimensions. | | `trackCount`, `rawTrackCount`, `tracks` | Stored visible tracks, renderer count before the cap, and bounded nested track objects. | | `initialItemsExposed`, `continuationDetected`, `continuationCount` | Initial-page visibility and continuation markers; continuation pages are not replayed. | | `source`, `sourceUrl`, `searchUrl`, `rank`, `page` | Input provenance and candidate position. | | `sourceRenderer`, `sourceTransport`, `extractionMethod`, `metadataSource` | Public renderer, direct/proxy transport, and extraction provenance. | | `metadataEnriched`, `albumPageAvailable` | Whether the detail page was fetched and parsed. | | `requestedMaxItems`, `requestedMaxSearchItems`, `requestedMaxStartItems`, `requestedMaxPages`, `requestedMaxTracks` | Effective limits recorded on the row. | | `includeTracks`, `languageCode`, `countryCode`, `scrapedAt` | Effective detail/locale settings and UTC emission time. | Each nested `tracks` item can contain `position`, `title`, `subtitle`, `description`, `descriptionLength`, `artist`, `channelName`, `channelId`, `channelUrl`, `duration`, `durationSeconds`, `views`, `viewsText`, `publishedTimeText`, `badges`, `videoId`, `videoUrl`, `musicUrl`, `thumbnailUrl`, `thumbnailCount`, `thumbnails`, and `sourceRenderer`. These are copied only when the public playlist or search renderer exposes them. ### Pagination, deduplication, and omissions - `startUrls` are processed first, then `searchQueries`; both contribute to `maxItems`. - Each search query uses one public search page. Each accepted candidate uses one public playlist or album detail page. - `maxPages` is a bounded, recorded setting for forward compatibility. Continuation markers are counted, but continuation tokens are not replayed. - Normal rows are deduplicated by `browseId`, so the same playlist found by multiple queries is emitted once. - There are no hidden filters or sort options. Source ordering and the emitted `rank` are preserved; `maxSearchItems` and `maxStartItems` are the available selection bounds. - `includeTracks: false` omits `tracks` and reports `trackCount: 0`. `maxTracks: 0` also retains no track rows. - `searchQuery` and `searchUrl` are omitted for rows produced only from `startUrls`; release fields are omitted when explicit official metadata is unavailable; missing source fields are omitted rather than invented. ### Proxy, access boundaries, and cost The default route is a direct public HTML request. With `enableProxyFallback: true`, a configured account-authorized Apify Proxy route is tried after direct failure. An explicitly configured proxy is used as the first route. Proxy state is reported in `OUTPUT`; proxy routing does not bypass access controls. This Actor adds no separate API or licensing fee. Your Apify account may incur the normal compute and, when used, proxy usage charges. Request limits and delays are exposed so runs can be sized deliberately. ### Troubleshooting #### The dataset contains only diagnostics Check `errorCode` and `OUTPUT`. `SEARCH_ACCESS_BLOCKED` or `ALBUM_ACCESS_BLOCKED` means the public route reported an access boundary. You may retry later or configure an account-authorized Apify Proxy route. A diagnostic is an honest availability result, not a fabricated album row. #### A search returns no albums Use a more specific album or artist query, or provide a known public playlist in `startUrls`. The search extractor keeps only album-like public playlist renderers and intentionally excludes generic mixes and unrelated playlists. #### Tracks or release dates are missing The source page did not expose those fields in its initial public data, or `includeTracks`/`maxTracks` limited them. Official release dates are never inferred from a title or description. #### The run is slow or uses too many requests Lower `maxItems`, `maxSearchItems`, `maxStartItems`, or `maxTracks`; increase `requestDelayMs` only when pacing is needed. Retries and proxy fallback multiply request attempts, and the summary reports `pageAttempts`. ### API and support For programmatic runs, use the [Apify Actor API run documentation](https://docs.apify.com/platform/actors/running/running-via-api) and pass the same JSON input object. The dataset and `OUTPUT` key-value record are available through the run’s default storage links. For a reproducible issue, include the sanitized input, run ID, `OUTPUT` summary, diagnostic rows, and the public URL category involved. Do not include proxy credentials, cookies, tokens, or private account data. ### Privacy, legal use, and affiliation Use only public pages and comply with YouTube’s terms, robots guidance, applicable law, and the rights of creators. Do not use this Actor to access private content, evade authentication, solve CAPTCHAs, or bypass access controls. This Actor is not affiliated with YouTube or Google. Results depend on what the public page exposes at run time. # Changelog This Actor's version history is a separate document: https://apify.com/w3crawler/youtube-music-albums-scraper/changelog.md # Actor input Schema ## `searchQueries` (type: `array`): Optional public YouTube album, artist, or genre searches. Queries are processed after direct playlist URLs and are deduplicated case-insensitively. ## `startUrls` (type: `array`): Optional public YouTube playlist URLs for direct album extraction. These are processed before search queries and count toward the global maxItems cap. ## `maxItems` (type: `integer`): Global cap on album or playlist records across all search queries and direct start URLs. ## `maxSearchItems` (type: `integer`): Maximum album-style results considered for each search query before the global cap. When omitted, it follows maxItems. ## `maxStartItems` (type: `integer`): Maximum direct playlist URLs processed before the global cap. When omitted, it follows maxItems. ## `maxPages` (type: `integer`): Bound recorded for public page work. This implementation fetches only each initial public search or playlist page; continuation availability is reported but continuation requests are not replayed. ## `includeTracks` (type: `boolean`): Store bounded visible tracks from each public playlist page. ## `maxTracks` (type: `integer`): Maximum visible tracks retained for each album playlist. ## `languageCode` (type: `string`): Language context used for public pages. ## `countryCode` (type: `string`): Two-letter country context used for public pages. ## `maxRetries` (type: `integer`): Bounded retries after a public page request fails. ## `requestTimeoutSecs` (type: `integer`): Timeout for one public HTML page request. ## `requestDelayMs` (type: `integer`): Bounded pacing delay between public page requests. ## `includeDiagnostics` (type: `boolean`): Write exact four-field public access diagnostics. ## `enableProxyFallback` (type: `boolean`): Try one configured Apify Proxy route after direct public-page failure. ## `proxyConfiguration` (type: `object`): Optional account-authorized Apify Proxy configuration. Keep proxy URLs credential-free. ## Actor input object example ```json { "searchQueries": [ "Adele album" ], "maxItems": 10, "maxSearchItems": 10, "maxStartItems": 10, "maxPages": 1, "includeTracks": true, "maxTracks": 50, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "includeDiagnostics": true, "enableProxyFallback": 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 album" ], "maxItems": 10, "maxSearchItems": 10, "maxStartItems": 10, "maxPages": 1, "includeTracks": true, "maxTracks": 50, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("w3crawler/youtube-music-albums-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 album"], "maxItems": 10, "maxSearchItems": 10, "maxStartItems": 10, "maxPages": 1, "includeTracks": True, "maxTracks": 50, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "includeDiagnostics": True, "enableProxyFallback": True, "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("w3crawler/youtube-music-albums-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 album" ], "maxItems": 10, "maxSearchItems": 10, "maxStartItems": 10, "maxPages": 1, "includeTracks": true, "maxTracks": 50, "languageCode": "en", "countryCode": "US", "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } }' | apify call w3crawler/youtube-music-albums-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/youtube-music-albums-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/UGHx0kv2ar6dDEbMR/builds/gdFoBuVLkq0eCJ8Zi/openapi.json