# ✨ Free Youtube Playlist Scraper (`toludare/youtube-playlist-scraper`) Actor

Your all-in-one tool for extracting data from YouTube playlists, including podcasts, courses, and releases. Retrieve rich details including titles, descriptions, thumbnails, full video and channel metadata, and engagement statistics.

- **URL**: https://apify.com/toludare/youtube-playlist-scraper.md
- **Developed by:** [tolu.](https://apify.com/toludare) (community)
- **Categories:** Videos, Developer tools, Automation
- **Stats:** 313 total users, 21 monthly users, 55.9% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## 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

## YouTube Playlist Scraper

Your all-in-one tool for extracting data from YouTube playlists; including podcasts, courses, and releases. Retrieve rich details such as titles, descriptions, thumbnails, full video and channel metadata, and engagement statistics.

### 😋 Features 😋

- Get complete playlist details including title, description, thumbnail, full channel and video metadata, and engagement statistics. Works across normal playlists, podcasts, courses, and releases.
- Easily switch proxy country to avoid hidden videos and region-restricted content.
- View a detailed summary stored in the key-value store after each run. Each input URL is categorized as either `complete`, `hasHiddenVideos`, `incomplete`, `unavailable`, or `failed`.

### Interested in other YouTube scraping tools?

Are you looking for full YouTube video and shorts metadata including engagement statistics and transcripts. Check out our [YouTube Metadata Scraper](https://apify.com/toludare/youtube-metadata-scraper-all).

### 👩‍🍳 Input 👩‍🍳

|Parameter|Type|Description|Default Value|
|:---------|:----|:-----------|:-------------:|
|startURLs|array\[link]|One or more Youtube playlist URLs. The maximum number of URLs is 1000.|-|
|useProxy|boolean|Turn on residential proxy|false|
|proxyCountry|CountrySelector|Select country for the RESIDENTIAL proxy. This is useful for playlists that contain videos only available in specific regions. Otherwise, the default `ANY` is recommended.|`ANY`|

#### Example

```json
{
    "startURLs": [
        "https://www.youtube.com/playlist?list=PLMvsN4LH5cSH-_-FOZVIrkrXa37hNthny"
    ],
    "useProxy": true,
    "proxyCountry": "ANY",
}
```

### 🍖 Output 🍖

|Parameter|Type|Description|
|:---------|:----|:-----------|
|input|link|Input URL given|
|id|string|Playlist ID|
|url|link|Playlist URL|
|title|string|Playlist Title|
|description|string|Playlist Description|
|playlistType|`Playlist`|`Podcast`|`Course`|`Album`|Playlist Type|
|thumbnail|link|Playlist Thumbnail|
|videoCount|integer|Number of videos in playlist|
|viewCount|integer|Number of times the playlist has been viewed|
|hiddenVideoCount|integer|Number of hidden videos in playlist. You can avoid this by turning on proxy and setting `proxyCountry` to the exact location where the videos are not restricted.|
|channelId|string|Playlist Channel ID|
|channelUrl|link|Playlist Channel URL|
|channelUsername|string|Playlist Channel Username|
|channelDisplayName|string|Playlist Channel Display Name|
|videos|array\[video]|Information of each video in the playlist|
|video.index|integer|Position of video in playlist|
|video.id|string|Video ID|
|video.url|link|Video URL|
|video.title|string|Video Title|
|video.thumbnail|link|Video Thumbnail (High Quality)|
|video.length|string|Video length, formatted in hours, minutes and seconds e.g. `3:48`. Hours and minute are omitted where they do not apply.|
|video.lengthSeconds|integer|Video length in seconds|
|video.viewCount|string|Number of views of video (inexact) e.g. `115K`, `1.2M`|
|video.relativeUploadTime|string|Upload time of video, relative to the current time e.g. `1 year ago`|
|video.channelId|string|Video Channel ID|
|video.channelUrl|link|Video Channel URL|
|video.channelUsername|string|Video Channel Username|
|video.channelDisplayName|string|Video Channel Display Name|

#### Example

```json
[
  {
    "input": "https://www.youtube.com/playlist?list=PLQ_voP4Q3cfdvAY-XP1-uq5NzJ1sZGtwj",
    "id": "PLQ_voP4Q3cfdvAY-XP1-uq5NzJ1sZGtwj",
    "url": "https://www.youtube.com/playlist?list=PLQ_voP4Q3cfdvAY-XP1-uq5NzJ1sZGtwj",
    "title": "The Best of Son Heung min",
    "description": null,
    "playlistType": "Playlist",
    "thumbnail": "https://i.ytimg.com/vi/mH5wcYC8oxM/hqdefault.jpg",
    "videoCount": 5,
    "viewCount": 2590,
    "hiddenVideoCount": 0,
    "channelID": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
    "channelURL": "https://www.youtube.com/@premierleague",
    "channelUsername": "premierleague",
    "channelDisplayName": "Premier League",
    "videos": [
      {
        "index": 1,
        "id": "mH5wcYC8oxM",
        "url": "https://www.youtube.com/watch?v=mH5wcYC8oxM",
        "title": "Son Heung-min: 10 Years of Smiles, Goals, and Greatness 🇰🇷",
        "thumbnail": "https://i.ytimg.com/vi/mH5wcYC8oxM/hqdefault.jpg",
        "length": "7:24",
        "lengthSeconds": 444,
        "viewCount": "410K",
        "relativeUploadTime": "2 months ago",
        "channelId": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
        "channelURL": "https://www.youtube.com/@premierleague",
        "channelUsername": "premierleague",
        "channelDisplayName": "Premier League"
      },
      {
        "index": 2,
        "id": "shkGWuni26w",
        "url": "https://www.youtube.com/watch?v=shkGWuni26w",
        "title": "11 of Son Heung-min's Best Moments in the Premier League",
        "thumbnail": "https://i.ytimg.com/vi/shkGWuni26w/hqdefault.jpg",
        "length": "7:06",
        "lengthSeconds": 426,
        "viewCount": "1.1M",
        "relativeUploadTime": "2 months ago",
        "channelId": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
        "channelURL": "https://www.youtube.com/@premierleague",
        "channelUsername": "premierleague",
        "channelDisplayName": "Premier League"
      },
      {
        "index": 3,
        "id": "2NaoEy7VszY",
        "url": "https://www.youtube.com/watch?v=2NaoEy7VszY",
        "title": "Son's Triple Seals Victory | Spurs 6-2 Leicester City | 2022/23 Premier League Highlights",
        "thumbnail": "https://i.ytimg.com/vi/2NaoEy7VszY/hqdefault.jpg",
        "length": "8:29",
        "lengthSeconds": 509,
        "viewCount": "101K",
        "relativeUploadTime": "8 months ago",
        "channelId": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
        "channelURL": "https://www.youtube.com/@premierleague",
        "channelUsername": "premierleague",
        "channelDisplayName": "Premier League"
      },
      {
        "index": 4,
        "id": "BXDp8iMF7J0",
        "url": "https://www.youtube.com/watch?v=BXDp8iMF7J0",
        "title": "Son Heung-min names FAVOURITE Premier League moment for Spurs | Ultimates",
        "thumbnail": "https://i.ytimg.com/vi/BXDp8iMF7J0/hqdefault.jpg",
        "length": "6:59",
        "lengthSeconds": 419,
        "viewCount": "96K",
        "relativeUploadTime": "1 year ago",
        "channelId": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
        "channelURL": "https://www.youtube.com/@premierleague",
        "channelUsername": "premierleague",
        "channelDisplayName": "Premier League"
      },
      {
        "index": 5,
        "id": "7aMutyZelts",
        "url": "https://www.youtube.com/watch?v=7aMutyZelts",
        "title": "'I'M GETTING EMOTIONAL...' 😢 Heartwarming moment Heung-Min Son surprises Spurs fan | Fan Mail",
        "thumbnail": "https://i.ytimg.com/vi/7aMutyZelts/hqdefault.jpg",
        "length": "6:30",
        "lengthSeconds": 390,
        "viewCount": "400K",
        "relativeUploadTime": "1 year ago",
        "channelId": "UCG5qGWdu8nIRZqJ_GgDwQ-w",
        "channelURL": "https://www.youtube.com/@premierleague",
        "channelUsername": "premierleague",
        "channelDisplayName": "Premier League"
      }
    ]
  }
]
```

### ❔ FAQ ❔

#### What does the `RUN_SUMMARY` file contain?

The RUN_SUMMARY file is created after each run and stored in the key-value store. It divides each playlist input URL into 5 categories:

- `complete` - this URL was successfully processed and all videos are complete.
- `hasHiddenVideos` - this URL was successfully processed but there are some hidden videos. This is usually due to location issues and you can solve this by turning the proxy on and setting an appropraite location. Check the Input section for more details.
- `incomplete` - Some videos were gotten but processing failed before it was completed.
- `unavailable` - The playlist is unavailable for some reason. Either it has been deleted or it is invalid
- `failed` - Processing failed completely and no videos were gotten.

#### Feedback

We’re always working on improving the performance of our Actors. So if you’ve got any technical feedback for YouTube Playlist scraper or simply found a bug, please create an issue on the Actor’s [Issues tab](https://console.apify.com/actors/HBfIVH1V38AybP1hF/issues) in Apify Console.

# Changelog

This Actor's version history is a separate document: https://apify.com/toludare/youtube-playlist-scraper/changelog.md

# Actor input Schema

## `startURLs` (type: `array`):

One or more Youtube playlist URLs. The maximum number of URLs is 1000.

## `useProxy` (type: `boolean`):

Turn on residential proxy

## `proxyCountry` (type: `string`):

Select country for the RESIDENTIAL proxy. This is useful for playlists that contain videos only available in specific regions. Otherwise, the default `Anywhere` is recommended.

## Actor input object example

```json
{
  "startURLs": [
    "https://www.youtube.com/playlist?list=PLcj4z4KsbIoWkmDJ2oxxyp6B3ttTOYOnB",
    "https://www.youtube.com/playlist?list=PLibNZv5Zd0dwEYACYgy9JjOgRxAwl-aHd",
    "https://www.youtube.com/watch?v=LagpKkQLTIg&list=PLibNZv5Zd0dyw0MMIc8JeoVg5Tf84zkUC&index=2"
  ],
  "useProxy": false,
  "proxyCountry": "ANY"
}
```

# 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 = {
    "startURLs": [
        "https://www.youtube.com/playlist?list=PLcj4z4KsbIoWkmDJ2oxxyp6B3ttTOYOnB",
        "https://www.youtube.com/playlist?list=PLibNZv5Zd0dwEYACYgy9JjOgRxAwl-aHd",
        "https://www.youtube.com/watch?v=LagpKkQLTIg&list=PLibNZv5Zd0dyw0MMIc8JeoVg5Tf84zkUC&index=2"
    ]
};

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

# Prepare the Actor input
run_input = { "startURLs": [
        "https://www.youtube.com/playlist?list=PLcj4z4KsbIoWkmDJ2oxxyp6B3ttTOYOnB",
        "https://www.youtube.com/playlist?list=PLibNZv5Zd0dwEYACYgy9JjOgRxAwl-aHd",
        "https://www.youtube.com/watch?v=LagpKkQLTIg&list=PLibNZv5Zd0dyw0MMIc8JeoVg5Tf84zkUC&index=2",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("toludare/youtube-playlist-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 '{
  "startURLs": [
    "https://www.youtube.com/playlist?list=PLcj4z4KsbIoWkmDJ2oxxyp6B3ttTOYOnB",
    "https://www.youtube.com/playlist?list=PLibNZv5Zd0dwEYACYgy9JjOgRxAwl-aHd",
    "https://www.youtube.com/watch?v=LagpKkQLTIg&list=PLibNZv5Zd0dyw0MMIc8JeoVg5Tf84zkUC&index=2"
  ]
}' |
apify call toludare/youtube-playlist-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,toludare/youtube-playlist-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 <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/HBfIVH1V38AybP1hF/builds/ov0fiBOL5fR8pat6K/openapi.json