# YouTube Playlist Search: find playlists by keyword, bulk (`steadydata/youtube-playlist-search`) Actor

Find YouTube playlists by keyword, up to 100 per query: one row per playlist with rank, title, playlist id and URL, the channel that owns it, how many videos it holds and its thumbnail. Search playlists for many keywords in one run. Pay per playlist.

- **URL**: https://apify.com/steadydata/youtube-playlist-search.md
- **Developed by:** [Steadydata Team](https://apify.com/steadydata) (community)
- **Categories:** Videos, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.28 / 1,000 playlist listeds

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

## YouTube Playlist Search: find playlists by keyword, bulk

Find YouTube playlists by keyword, up to 100 per query: one row per playlist with rank, title, playlist id and URL, the channel that owns it, how many videos it holds and its thumbnail. Search playlists for many keywords in one run. Pay per playlist.

### Why this scraper

- **Only delivered results are charged.** Queries that return no playlists come back as a
  clear error record at no cost.
- **YouTube's own ranking, not ours.** Results come from the playlist filter YouTube applies
  when a visitor picks "Playlist" under Filters, so the order is the order a visitor sees.
- **Light on the source.** One request carries 20 playlists in about 51 KB, so roughly 2.5 KB
  per delivered playlist (measured 30-09-2026). No browser, no rendering, no page loads.
- **Bulk in one run.** Up to 100 keywords per run, each with its own cost ceiling.

### Who this is for

People who need to find playlists rather than read one they already know: researchers mapping
what exists on a topic, teams building course or music catalogues, and anyone feeding a list of
playlist URLs into another tool. It pairs with two actors that take over from here: one lists
every video inside a playlist, another pulls the transcripts of those videos.

### Who this is not for

This finds playlists and describes them; it does not open them. You get the playlist id, its
URL, the owning channel and how many videos it holds, but not the videos themselves. For that,
run YouTube Playlist Videos on the URLs this actor returns. Private and unlisted playlists are
not searchable and will never appear here.

### Input fields

| Field | Type | Required or default | What it does |
|---|---|---|---|
| `queries` | list of text | required | One keyword per row, up to 100. Each query returns the playlists YouTube ranks for it, in that order. |
| `maxPlaylistsPerQuery` | number | 20 | Cost ceiling per query, in YouTube's ranking order. |
| `country` | text | US | Two-letter country the anonymous viewer is placed in; results differ per country. |
| `language` | text | en | Two-letter interface language for titles and counts. |

### Input example

```json
{
    "queries": [
        "python tutorial",
        "jazz piano",
        "home workout"
    ],
    "maxPlaylistsPerQuery": 20,
    "country": "US",
    "language": "en"
}
```

### Output example

| Field | Type | What it holds | Example |
|---|---|---|---|
| `query` | text | The search keyword this row came from, so a bulk run stays traceable. | `python tutorial` |
| `position` | number | The place of the playlist in YouTube's ranking for that keyword, counting from 1. | `1` |
| `playlistId` | text | The playlist id, the part after list= in a YouTube URL. | `PLsyeobzWxl7poL9JTVyndKe62ieoN-MZ3` |
| `url` | text | The playlist page on YouTube, ready to open or to feed into another actor. | `https://www.youtube.com/playlist?list=PLsyeobzWxl7poL9JTV...` |
| `title` | text | The playlist title as its owner wrote it. | `Python for Beginners (Full Course) \| Programming Tutorial` |
| `channelName` | text | The channel that owns the playlist. | `Telusko` |
| `channelId` | text | The channel id, stable even when the channel is renamed. | `UC59K-uG2A5ogwIrHw4bmlEg` |
| `channelUrl` | text | The channel page on YouTube. | `https://www.youtube.com/channel/UC59K-uG2A5ogwIrHw4bmlEg` |
| `videoCount` | number | How many videos the playlist holds in total. | `124` |
| `thumbnailUrl` | text | The widest thumbnail YouTube offers for the playlist, as an absolute link. | `https://i.ytimg.com/vi/QXeEoD0pB3E/hqdefault.jpg` |

Error codes: `EMPTY_QUERY`, `NO_PLAYLISTS`, `BLOCKED`.

A real row from the run of 30-09-2026:

```json
{
  "query": "python tutorial",
  "position": 2,
  "playlistId": "PL-osiE80TeTt2d9bfVyTiXJA-UTHn6WwU",
  "url": "https://www.youtube.com/playlist?list=PL-osiE80TeTt2d9bfVyTiXJA-UTHn6WwU",
  "title": "Python Tutorials",
  "channelName": "Corey Schafer",
  "channelId": "UCCezIgC97PvUuR4_gbFUs5g",
  "channelUrl": "https://www.youtube.com/channel/UCCezIgC97PvUuR4_gbFUs5g",
  "videoCount": 158,
  "thumbnailUrl": "https://i.ytimg.com/vi/YYXdXT2l-Gg/hqdefault.jpg"
}
```

### Related actors from steadydata

- [youtube-playlist-videos](https://apify.com/steadydata/youtube-playlist-videos): every video inside the playlists you found
- [youtube-playlist-transcripts](https://apify.com/steadydata/youtube-playlist-transcripts): the transcript of every video in a playlist
- [youtube-channel-playlists](https://apify.com/steadydata/youtube-channel-playlists): all playlists of one channel instead of a keyword

### Pricing

Pay per event: one `playlist-listed` event per delivered result. No charge for inputs
that fail, no separate platform-usage surcharge.

### FAQ

**How many playlists do I get per keyword?**
As many as you set in `maxPlaylistsPerQuery`, up to 100. YouTube returns them 20 at a time and
the actor pages through until your ceiling is reached or YouTube runs out. Popular keywords
reach 100; narrow ones stop earlier, and you only pay for what arrives.

**Are the results the same as what I see in my browser?**
They are the results an anonymous viewer sees in the country and language you set, which is not
always what a logged-in viewer sees. Set `country` and `language` to match the audience you care
about; both change the ranking.

**Can I feed these playlists into another actor?**
Yes, that is the point. The `url` field is a normal playlist URL. YouTube Playlist Videos takes
those URLs and returns every video inside; YouTube Playlist Transcripts returns the transcripts.

**What happens if a keyword returns nothing?**
You get one free error record with the code `NO_PLAYLISTS` and that keyword is not charged. The
run itself still succeeds, so one dead keyword never costs you the rest of the batch.

**Is personal data collected?**
No. A playlist has a title, an owning channel and a video count; none of that identifies a
person. The channel is the publisher of the playlist, the same name the store page shows.

**What happens when the source changes?**
Sources change from time to time; that is the nature of this work. The actor is
monitored daily and fixed fast, and while it is broken you are not charged, because
only delivered results cost anything.

# Changelog

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

# Actor input Schema

## `queries` (type: `array`):

One keyword per row, up to 100. Each query returns the playlists YouTube ranks for it, in that order.

## `maxPlaylistsPerQuery` (type: `integer`):

Cost ceiling per query, in YouTube's ranking order.

## `country` (type: `string`):

Two-letter country the anonymous viewer is placed in; results differ per country.

## `language` (type: `string`):

Two-letter interface language for titles and counts.

## Actor input object example

```json
{
  "queries": [
    "python tutorial",
    "jazz piano",
    "home workout"
  ],
  "maxPlaylistsPerQuery": 20,
  "country": "US",
  "language": "en"
}
```

# 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 = {
    "queries": [
        "python tutorial",
        "jazz piano",
        "home workout"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("steadydata/youtube-playlist-search").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 = { "queries": [
        "python tutorial",
        "jazz piano",
        "home workout",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("steadydata/youtube-playlist-search").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 '{
  "queries": [
    "python tutorial",
    "jazz piano",
    "home workout"
  ]
}' |
apify call steadydata/youtube-playlist-search --silent --output-dataset

```

## MCP server setup

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

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/AyTjCHc0VVLiszSfX/builds/IwVXrB8F1kggoJsCX/openapi.json