# YouTube Music Podcast Scraper (`w3crawler/youtube-music-podcast-scraper`) Actor Search current YouTube Music podcast shows and episodes through first-party youtubei endpoints, continuation pagination, enrichment, and deduplication. - **URL**: https://apify.com/w3crawler/youtube-music-podcast-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 podcasts 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 Search public [YouTube](https://www.youtube.com/) pages for podcast episodes, shows/playlists, and creator channels. The Actor parses the public HTML delivered to an unauthenticated visitor and can optionally enrich episodes from public watch pages, shows from public playlist pages, and channels from public channel pages. ### What this Actor does Use this Actor to: - Discover public podcast episodes, show playlists, and creator channels from search terms. - Inspect a known public watch, playlist, channel, or handle URL. - Keep source-backed titles, descriptions, durations, publication text, views, identities, artwork, and public links together. - Add optional public watch-page episode metadata or bounded playlist/channel details. - Measure public access boundaries with small, explicit diagnostic rows. The Actor emits a creator channel as `type: "channel"`; it does not relabel a channel as a podcast show. `podcastMatch` is a transparent title/description/query signal, not a hidden ranking or guarantee that the source describes a podcast. ### Input Provide at least one `searchQueries` entry or one public `startUrls` entry. 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. Search terms are normalized and deduplicated case-insensitively. Start URLs are canonicalized and duplicate canonical URLs are rejected. #### Input fields | Field | Type and limits | Behavior | | ----------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `searchQueries` | string array, up to 25 items; each 1–200 characters | Optional public podcast, show, or episode searches. | | `startUrls` | string array, up to 50 items | Optional public YouTube watch, playlist, channel, `@handle`, `/c/`, or `/user/` URLs. Credentials and non-YouTube hosts are rejected. | | `maxItems` | integer, 1–100; default `50` | Global cap on deduplicated normal episode/show/channel records. | | `maxPages` | integer, 1–5; default `1` | Maximum public search pages per query. Page URLs are bounded; continuation markers are reported but continuation tokens are not replayed. | | `maxShowEpisodes` | integer, 1–50; default `10` | Maximum visible episodes retained inside each show detail object. | | `maxRetries` | integer, 0–3; default `1` | Bounded retries after a public page request fails. | | `requestTimeoutSecs` | integer, 15–180; default `60` | Timeout for one public HTML request. | | `requestDelayMs` | integer, 0–5000; default `250` | Delay between page requests. | | `countryCode` | two letters; default `US` | Country context for public pages. | | `languageCode` | 2–3 letters with optional locale suffix; default `en` | Language context for public pages. | | `includeShowDetails` | boolean; default `true` | Enrich show results from public playlist pages and channel URL results when available. | | `includeEpisodeDetails` | boolean; default `true` | Attempt optional public watch-page metadata for episode results. | | `includeDiagnostics` | boolean; default `true` | Emit exact four-field diagnostics for access or optional-enrichment failures. | | `enableProxyFallback` | boolean; default `true` | Try one configured Apify Proxy request after a direct public-page failure. | | `proxyConfiguration` | Apify Proxy object; optional | Account-authorized proxy configuration. Proxy URLs must be credential-free. | #### Runnable input examples Public podcast search: ```json { "searchQueries": ["technology podcast"], "maxItems": 5, "maxPages": 1, "includeShowDetails": true, "includeEpisodeDetails": true, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } } ``` Known public episode: ```json { "startUrls": ["https://www.youtube.com/watch?v=7ARBJQn6QkM"], "maxItems": 1, "includeEpisodeDetails": true, "includeShowDetails": false, "enableProxyFallback": false } ``` Known playlist plus search, with bounded enrichment: ```json { "searchQueries": ["technology podcast", "AI interview podcast"], "startUrls": [ "https://www.youtube.com/playlist?list=PLADd6sStSis77HKfbf4KCY6SvthfxeUgn" ], "maxItems": 8, "maxPages": 2, "maxShowEpisodes": 5, "maxRetries": 1, "requestTimeoutSecs": 45, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includeShowDetails": true, "includeEpisodeDetails": false, "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 keep 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, enrichment availability, access state, limits, and duration. ### Output #### Normal episode record Normal rows have `recordType: "youtube_public_podcast_result"` and `type: "episode"`, `"show"`, or `"channel"`. This rich example is source-shaped; values not exposed by the public page are omitted. ```json { "recordType": "youtube_public_podcast_result", "type": "episode", "searchQuery": "technology podcast", "title": "The Big Technology Podcast", "description": "A public conversation about technology and business.", "descriptionLength": 52, "subtitle": "Big Technology · 2 years ago · 120K views", "showName": "The Big Technology Podcast", "channelName": "Big Technology", "channelId": "UCye1YedIypHffYb8k6Gp9wg", "channelUrl": "https://www.youtube.com/channel/UCye1YedIypHffYb8k6Gp9wg", "duration": "1:02:15", "durationSeconds": 3735, "publishedText": "2 years ago", "views": 120000, "viewsText": "120K views", "videoId": "7ARBJQn6QkM", "videoUrl": "https://www.youtube.com/watch?v=7ARBJQn6QkM", "youtubeMusicUrl": "https://music.youtube.com/watch?v=7ARBJQn6QkM", "thumbnails": [ { "url": "https://i.ytimg.com/vi/7ARBJQn6QkM/hqdefault.jpg", "width": 480, "height": 360 } ], "thumbnailUrl": "https://i.ytimg.com/vi/7ARBJQn6QkM/hqdefault.jpg", "thumbnailCount": 1, "badges": [], "isLive": false, "isUpcoming": false, "podcastMatch": true, "sourceRenderer": "public-video-renderer", "episodeDetailsAvailable": true, "episodeDetailsStatus": "available", "episodeTransport": "youtube-public-watch-page", "episode": { "title": "The Big Technology Podcast", "description": "A public conversation about technology and business.", "descriptionLength": 52, "channelName": "Big Technology", "channelId": "UCye1YedIypHffYb8k6Gp9wg", "channelUrl": "https://www.youtube.com/channel/UCye1YedIypHffYb8k6Gp9wg", "lengthSeconds": 3735, "publishDate": "2024-01-10", "uploadDate": "2024-01-10", "viewCount": 120000, "category": "Science & Technology", "keywords": ["technology", "podcast"], "isLive": false, "playerStatus": "OK", "captionCount": 2, "captions": [ { "languageCode": "en", "name": "English", "kind": "asr" } ], "hasVideo": true, "hasAudio": true, "formatCount": 8, "metadataSource": "youtube-public-watch-page", "extractionMethod": "youtube-public-watch-page-embedded-player-data" }, "searchUrl": "https://www.youtube.com/results?search_query=technology+podcast&hl=en&gl=US", "source": "search", "sourceUrl": "https://www.youtube.com/results?search_query=technology+podcast&hl=en&gl=US", "rank": 1, "page": 1, "initialItemsExposed": 6, "continuationDetected": false, "continuationCount": 0, "sourceTransport": "public-rendered-html-direct", "extractionMethod": "youtube-public-page-embedded-initial-data", "metadataSource": "youtube-public-watch-page", "metadataEnriched": true, "requestedMaxItems": 5, "requestedMaxPages": 1, "requestedMaxShowEpisodes": 10, "languageCode": "en", "countryCode": "US", "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` #### Show and channel records `type: "show"` may include a `show` object with public episode/view counts, creator identity, artwork, and at most `maxShowEpisodes` visible episodes. `type: "channel"` may include a `channel` object with public creator, subscriber/video text, description, artwork, and the canonical public channel URL. Detail objects are optional and are not synthesized when the page does not expose them. #### Fallback and diagnostic record With `enableProxyFallback: true`, a configured Apify Proxy route is tried after direct public-page failure. Optional enrichment failure does not discard a valid core result; its availability status becomes `unavailable` and a diagnostic is emitted when diagnostics are enabled. If a required page remains blocked or unparsable, the diagnostic has exactly these four fields: ```json { "url": "https://www.youtube.com/watch?v=7ARBJQn6QkM", "error": "Public YouTube page was blocked (HTTP 403).", "errorCode": "EPISODE_ACCESS_BLOCKED", "scrapedAt": "2026-09-08T12:00:00.000Z" } ``` Diagnostics are not normal podcast records. The Actor never invents episode titles, show identities, dates, counts, captions, or media URLs. #### `OUTPUT` summary The `OUTPUT` key-value record reconciles normal and diagnostic counts and records optional-enrichment availability: ```json { "runType": "youtube-public-podcast-run", "status": "success", "dataAvailable": true, "sourceCount": 2, "sourcesWithItems": 2, "searchPagesFetched": 1, "playlistPagesFetched": 1, "watchPagesFetched": 0, "pageAttempts": 4, "itemCount": 3, "diagnosticCount": 0, "failedCount": 0, "blockedCount": 0, "continuationDetected": true, "continuationCount": 1, "episodeDetailsRequested": 2, "episodeDetailsAvailableCount": 2, "episodeDetailsUnavailableCount": 0, "showDetailsRequested": 1, "showDetailsAvailableCount": 1, "showDetailsUnavailableCount": 0, "channelDetailsRequested": 0, "channelDetailsAvailableCount": 0, "channelDetailsUnavailableCount": 0, "proxyRequested": true, "proxyConfigured": true, "includeDiagnostics": true, "includeShowDetails": true, "includeEpisodeDetails": true, "maxItems": 5, "maxPages": 1, "maxShowEpisodes": 10, "maxRetries": 1, "requestDelayMs": 250, "requestTimeoutSecs": 60, "languageCode": "en", "countryCode": "US", "paginationMethod": "bounded-public-search-pages-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 copied from public source data or identify the request and extraction path. Optional fields are omitted when not exposed or not applicable. | Field group | Fields and meaning | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Identity | `recordType`, `type`, `title`, `videoId`, `episodeBrowseId`, `showBrowseId`, `showId`, `channelBrowseId`, `channelId` identify the public result. | | Public text | `description`, `descriptionLength`, `accessibilityText`, `subtitle`, `showName`, `channelName`, `duration`, `publishedText`, `viewsText`, `podcastFormat`, `badges` preserve visible text and labels. | | Public metrics | `durationSeconds` and `views` are parsed values; source text remains in `duration`, `viewsText`, and `publishedText`. | | Public links and artwork | `channelUrl`, `showUrl`, `videoUrl`, `youtubeMusicUrl`, `thumbnailUrl`, `thumbnailCount`, and `thumbnails` contain normalized public URLs and dimensions. | | Classification | `isLive`, `isUpcoming`, and `podcastMatch` retain source flags and the transparent podcast signal. | | Optional episode detail | `episodeDetailsAvailable`, `episodeDetailsStatus`, `episodeTransport`, and `episode` contain public watch-page metadata without caption URLs, signatures, streaming URLs, or playback URLs. | | Optional show detail | `showDetailsAvailable`, `showDetailsStatus`, and `show` contain public playlist metadata and bounded nested `episodes`. | | Optional channel detail | `channelDetailsAvailable`, `channelDetailsStatus`, and `channel` contain public channel metadata. | | Provenance | `source`, `sourceUrl`, `searchUrl`, `rank`, `page`, `initialItemsExposed`, `continuationDetected`, `continuationCount`, `sourceRenderer`, `sourceTransport`, `extractionMethod`, `metadataSource`, and `metadataEnriched` explain where and how the row was obtained. | | Effective settings | `requestedMaxItems`, `requestedMaxPages`, `requestedMaxShowEpisodes`, `languageCode`, `countryCode`, and `scrapedAt` record run settings and UTC emission time. | | Diagnostics | `url`, `error`, `errorCode`, and `scrapedAt` are the only fields in a diagnostic row. | An `episode` object can contain `title`, `description`, `descriptionLength`, `channelName`, `channelId`, `channelUrl`, `lengthSeconds`, `publishDate`, `uploadDate`, `viewCount`, `category`, `keywords`, `isLive`, `playerStatus`, `playerReason`, `captionCount`, `captions`, `hasVideo`, `hasAudio`, `formatCount`, `metadataSource`, and `extractionMethod`. Caption items contain only `languageCode`, `name`, and `kind`. A `show` object can contain `id`, `title`, `description`, `episodeCount`, `episodeCountText`, `viewCount`, `viewCountText`, `updatedText`, `creatorName`, `creatorId`, `creatorUrl`, `subscriberCountText`, `videoCountText`, `thumbnailUrl`, `thumbnails`, `showUrl`, `episodes`, and `metadataSource`. Each nested show episode can contain `title`, `description`, `videoId`, `duration`, `durationSeconds`, `publishedText`, `views`, `viewsText`, `videoUrl`, `youtubeMusicUrl`, `thumbnailUrl`, and `thumbnails`. A `channel` object can contain `id`, `title`, `description`, `creatorName`, `creatorId`, `creatorUrl`, `subscriberCountText`, `videoCountText`, `thumbnailUrl`, `thumbnails`, `channelUrl`, and `metadataSource`. ### Pagination, deduplication, and omissions - Direct `startUrls` run before `searchQueries` and all normal records count toward `maxItems`. - A search query fetches up to `maxPages` bounded public search pages. Continuation markers are counted, but undocumented continuation tokens are not replayed. - A playlist start URL emits a show record and then visible episode records until `maxItems`; a watch URL emits one episode record; a channel or handle URL emits one channel record. - Normal rows are deduplicated by `videoId`, `showBrowseId`/`showId`, or `channelId`. The same public result found by multiple sources is emitted once. - There are no hidden filters or sort options. Source ordering and `rank` are preserved; `podcastMatch` is a signal only. - `includeShowDetails: false` skips optional show/channel enrichment. `includeEpisodeDetails: false` skips optional watch-page enrichment. Missing source fields and disabled optional objects are omitted rather than fabricated. ### 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 attempted after direct failure. Explicit proxy input uses the requested proxy configuration first. Transport and proxy state are reported in each row and 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, retries, and pacing are exposed so runs can be sized deliberately. ### Troubleshooting #### The dataset contains only diagnostics Check `errorCode` and `OUTPUT`. `ACCESS_BLOCKED`, `SEARCH_PAGE_FAILED`, or `START_URL_FAILED` indicates a public access or parsing boundary. Retry later or configure an account-authorized Apify Proxy route. A diagnostic is an honest availability result, not a substitute normal row. #### Optional details are unavailable The core search or start-URL record can still be valid. Review `episodeDetailsStatus`, `showDetailsStatus`, or `channelDetailsStatus`; optional failure is bounded and does not trigger private request methods. #### A search contains unrelated results YouTube search is broad. Use a more specific query and inspect `podcastMatch`, `type`, `sourceRenderer`, and the public title/description. The Actor does not claim that every search result is a podcast. #### The run is slow or uses too many requests Lower `maxItems`, `maxPages`, or `maxShowEpisodes`; set `includeShowDetails` or `includeEpisodeDetails` to `false`; increase `requestDelayMs` only when pacing is needed. Retries and proxy fallback multiply attempts, and `pageAttempts` reports the total. ### 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. The Actor does not use login state, CAPTCHA bypass, stealth browser automation, fingerprint spoofing, private request clients, or signed media extraction. 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-podcast-scraper/changelog.md # Actor input Schema ## `searchQueries` (type: `array`): Optional. Up to 25 public podcast, show, or episode searches. Queries are normalized and deduplicated case-insensitively after direct start URLs are processed. ## `startUrls` (type: `array`): Optional. Public watch, playlist, channel, or handle URLs. These are processed before search queries and count toward maxItems. ## `maxItems` (type: `integer`): Maximum deduplicated episode/show/channel records across the entire run (1–100). ## `maxPages` (type: `integer`): Bounded public search pages per query (1–5). Continuation markers are reported but not called. ## `maxShowEpisodes` (type: `integer`): Maximum visible playlist episodes retained inside a show detail object (1–50). ## `maxRetries` (type: `integer`): Bounded retries after a public page request fails (0–3). ## `requestTimeoutSecs` (type: `integer`): Timeout for each public HTML page request (15–180 seconds). ## `requestDelayMs` (type: `integer`): Bounded pacing delay between public page requests (0–5000 ms). ## `countryCode` (type: `string`): Two-letter country context used for public pages. ## `languageCode` (type: `string`): Two- or three-letter language context used for public pages. ## `includeShowDetails` (type: `boolean`): Fetch public playlist/channel details for show results when available. ## `includeEpisodeDetails` (type: `boolean`): Attempt optional public watch-page metadata for episode results. ## `includeDiagnostics` (type: `boolean`): Write exact four-field access or optional-enrichment diagnostics. ## `enableProxyFallback` (type: `boolean`): Try one configured Apify Proxy request after a direct public-page failure. ## `proxyConfiguration` (type: `object`): Optional account-authorized Apify Proxy configuration or credential-free HTTP/SOCKS URLs. ## Actor input object example ```json { "searchQueries": [ "technology podcast" ], "maxItems": 50, "maxPages": 1, "maxShowEpisodes": 10, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includeShowDetails": true, "includeEpisodeDetails": true, "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": [ "technology podcast" ], "maxItems": 50, "maxPages": 1, "maxShowEpisodes": 10, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includeShowDetails": true, "includeEpisodeDetails": true, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("w3crawler/youtube-music-podcast-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": ["technology podcast"], "maxItems": 50, "maxPages": 1, "maxShowEpisodes": 10, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includeShowDetails": True, "includeEpisodeDetails": True, "includeDiagnostics": True, "enableProxyFallback": True, "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("w3crawler/youtube-music-podcast-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": [ "technology podcast" ], "maxItems": 50, "maxPages": 1, "maxShowEpisodes": 10, "maxRetries": 1, "requestTimeoutSecs": 60, "requestDelayMs": 250, "countryCode": "US", "languageCode": "en", "includeShowDetails": true, "includeEpisodeDetails": true, "includeDiagnostics": true, "enableProxyFallback": true, "proxyConfiguration": { "useApifyProxy": false } }' | apify call w3crawler/youtube-music-podcast-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/youtube-music-podcast-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/xrGpu5yXbRMtI5QEz/builds/YpJFLdTSSsgsDJemS/openapi.json