# YouTube Shows Scraper (`beautifulscrape/youtube-shows`) Actor

Extract shows from YouTube channels and expand each show into its episodes. Accepts channel URLs/handles and direct show/playlist URLs.

- **URL**: https://apify.com/beautifulscrape/youtube-shows.md
- **Developed by:** [Beautiful Scrape](https://apify.com/beautifulscrape) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 is YouTube Shows Scraper?

YouTube Shows Scraper lets you extract shows from YouTube channels and expand each show into its episodes — helping you track series, analyze episodic content, and gather show metadata with just a few clicks.

**Discover channel shows**: list every show on a channel's Shows tab
**Expand show episodes**: get each episode with title, duration, views, and position
**Scrape direct show URLs**: process individual shows or playlist-backed show links
**Analyze episodic content**: understand how creators package videos into shows and seasons
**Automate show collection**: replace manual browsing with repeatable workflows that keep datasets fresh and consistent

The scraper opens each channel's Shows tab, discovers shows, then expands each one into individual episode rows with parent show metadata attached. YouTube Shows are playlist-backed, so direct playlist URLs are also accepted.

### What data does YouTube Shows Scraper extract?

📝 **Title** - The episode title

🆔 **Video ID** - The unique YouTube video ID

🔗 **URL** - Direct link to the episode (includes show/playlist + index when available)

⏱️ **Duration** - Length of the episode

👁️ **View Count** - Number of views on the episode

📅 **Date** - Upload date when available

🖼️ **Thumbnail URL** - Thumbnail image for the episode

📺 **Channel Name** - Name of the channel that owns the show

🌐 **Channel URL** - Link to the channel page

🆔 **Channel ID** - YouTube channel ID

🎬 **Show Title** - Title of the parent show

🆔 **Show ID** - YouTube show / playlist ID

🔗 **Show URL** - Direct link to the show page

🔢 **Show Episode Count** - Number of episodes in the show (when shown on the tab)

🔢 **Order** - 1-based position of the episode in the show

🏷️ **Type** - Always `"episode"` for items from this actor

### Features

For maximum usefulness, YouTube Shows Scraper has the following abilities:

**List and expand**: discover shows on a channel, then emit one row per episode inside each show

**Flexible input**: scrape from channel handles/URLs and/or direct show/playlist URLs in one run

**Result limits**: control how many shows per channel (`maxResultsShows`) and how many episodes per show (`maxResultsEpisodesPerShow`)

**Automatic pagination**: handles Shows tab continuation pages and episode enumeration

**Error resilience**: continues processing remaining inputs even if one fails

**Structured output**: export data in JSON, CSV, Excel, or HTML with a consistent schema

### ⬇️ Input

Provide at least one of: channels or show URLs. You can set up the input programmatically or use the fields in the Actor's interface.

#### Channels

You can provide one or more YouTube channels using the `channels` array. The actor opens each channel's Shows tab.

**Supported channel formats**:

- Username: `MrBeast`
- Handle: `@MrBeast`
- Channel URL: `https://www.youtube.com/@MrBeast`
- Shows tab URL: `https://www.youtube.com/@MrBeast/shows`
- Channel ID URL: `https://www.youtube.com/channel/UCxxx`

#### Show URLs

Use `showUrls` to expand one or more shows directly.

**Supported URL formats**:

- Show page: `https://www.youtube.com/show/VLPLxxxxxxxx`
- Playlist URL: `https://www.youtube.com/playlist?list=PLxxxxxxxx`

#### Input Parameters

Provide **at least one** of:

- `channels` (array) - Channel usernames or URLs
- `showUrls` (array) - Direct show or playlist URLs

**Optional:**

- `maxResultsShows` (integer, default: 10) - Max shows to discover per channel
- `maxResultsEpisodesPerShow` (integer, default: 50) - Max episodes to expand per show

#### Example Input (channels)

```json
{
  "channels": ["MrBeast"],
  "maxResultsShows": 5,
  "maxResultsEpisodesPerShow": 20
}
```

#### Example Input (direct show)

```json
{
  "showUrls": [
    "https://www.youtube.com/show/VLPLoSWVnSA9vG9hJNdgr-81MG59EYT9eEYn"
  ],
  "maxResultsEpisodesPerShow": 10
}
```

#### Example Input (combined)

```json
{
  "channels": ["MrBeast"],
  "showUrls": [
    "https://www.youtube.com/playlist?list=PLoSWVnSA9vG9hJNdgr-81MG59EYT9eEYn"
  ],
  "maxResultsShows": 2,
  "maxResultsEpisodesPerShow": 10
}
```

### ⬆️ Output

The results will be wrapped into a dataset which you can find in the Output or Storage tab. Note that the output is organized in tables and tabs for viewing convenience. You can view results as a table, JSON, or other formats.

Once the run is finished, you can also download the dataset in various data formats (JSON, CSV, Excel, XML, HTML). Before exporting, you can pick or omit specific output fields.

**Important:** the actor does **not** emit one row per show. It emits **one row per episode** inside each discovered/expanded show, with show metadata attached.

#### JSON Output

Here's an example of the data structure for a single episode inside a show:

```json
{
  "id": "tnTPaLOaHz8",
  "title": "$10,000 Every Day You Survive In A Grocery Store",
  "url": "https://www.youtube.com/watch?v=tnTPaLOaHz8&list=PLoSWVnSA9vG8hI-SUpAimvYJrPh-PRRvp&index=1",
  "duration": "19:42",
  "viewCount": 547000000,
  "date": null,
  "type": "episode",
  "thumbnailUrl": "https://i.ytimg.com/vi/tnTPaLOaHz8/hqdefault.jpg",
  "showId": "PLoSWVnSA9vG8hI-SUpAimvYJrPh-PRRvp",
  "showTitle": "If You Survive, You Win",
  "showUrl": "https://www.youtube.com/show/VLPLoSWVnSA9vG8hI-SUpAimvYJrPh-PRRvp",
  "showEpisodeCount": 17,
  "channelName": "MrBeast",
  "channelUrl": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
  "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA",
  "fromYTUrl": "https://www.youtube.com/show/VLPLoSWVnSA9vG8hI-SUpAimvYJrPh-PRRvp",
  "order": 1,
  "input": "MrBeast"
}
```

#### Output Fields

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | null | The episode title |
| `type` | string | Always `"episode"` |
| `id` | string | The unique YouTube video ID |
| `url` | string | Direct link to the episode (with show/playlist context when available) |
| `thumbnailUrl` | string | null | Thumbnail image URL |
| `viewCount` | number | null | Number of views on the episode |
| `date` | string | null | Upload date (ISO format) when available |
| `duration` | string | null | Length of the episode |
| `showId` | string | null | YouTube show / playlist ID |
| `showTitle` | string | null | Title of the parent show |
| `showUrl` | string | null | Direct link to the show page |
| `showEpisodeCount` | number | null | Number of episodes in the show |
| `channelName` | string | null | Name of the channel |
| `channelUrl` | string | null | Link to the channel page |
| `channelId` | string | null | YouTube channel ID |
| `fromYTUrl` | string | The show URL that was scraped/expanded |
| `order` | number | 1-based position in the show |
| `input` | string | Original input value (channel or show URL) |

### Error items

When the scraper cannot retrieve data for a given input — for example a channel does not exist or a show has no episodes — it pushes an error item to the dataset instead of silently skipping it. Normal output items are never affected; you can tell them apart by the presence of an `error` field.

#### Error item structure

```json
{
  "url": "https://www.youtube.com/@somechannel",
  "input": "somechannel",
  "error": "CHANNEL_HAS_NO_SHOWS",
  "note": "Channel exists but has no shows"
}
```

#### Error codes reference

| Error code | Meaning |
|---|---|
| `CHANNEL_DOES_NOT_EXIST` | Channel URL points to a channel that does not exist |
| `CHANNEL_HAS_NO_SHOWS` | Channel exists but has no shows |
| `NO_VIDEOS` | Show exists but has no episodes |
| `NOT_FOUND` | Page or show was not found |
| `INVALID_INPUT` | Actor failed due to bad configuration or a malformed URL |

# Actor input Schema

## `channels` (type: `array`):

Channel usernames (with or without @) or channel URLs. The actor opens each channel's Shows tab.

## `showUrls` (type: `array`):

Direct YouTube show or playlist URLs (e.g. https://www.youtube.com/show/VLPLxxx or https://www.youtube.com/playlist?list=PLxxx).

## `maxResultsShows` (type: `integer`):

Maximum number of shows to discover from each channel's Shows tab.

## `maxResultsEpisodesPerShow` (type: `integer`):

Maximum number of episodes to expand from each show.

## Actor input object example

```json
{
  "channels": [
    "MrBeast"
  ],
  "maxResultsShows": 10,
  "maxResultsEpisodesPerShow": 50
}
```

# Actor output Schema

## `results` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "channels": [
        "MrBeast"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("beautifulscrape/youtube-shows").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "channels": ["MrBeast"] }

# Run the Actor and wait for it to finish
run = client.actor("beautifulscrape/youtube-shows").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 '{
  "channels": [
    "MrBeast"
  ]
}' |
apify call beautifulscrape/youtube-shows --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,beautifulscrape/youtube-shows"
        }
    }
}
```

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 <APIFY_API_TOKEN>` 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/6QOuhVuEELZU1BkJG/builds/4O7AR7iXbesdqMpAV/openapi.json