YouTube Music Albums Scraper

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, and the public Music destination is YouTube Music. 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:

{
  "searchQueries": ["Adele album"]
}

Known public playlist, with deterministic direct processing:

{
  "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:

{
  "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.

{
  "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:

{
  "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:

{
  "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 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.