YouTube Playlist¶
Fetch metadata for a single YouTube playlist — title, description, stated video count, view count, last-updated text, and the owning channel — from a playlist ID or any playlist URL.
| Method | Endpoint | Returns |
|---|---|---|
GET |
/v1/youtube/playlist |
Playlist metadata object |
Base URL: https://youtube.toolkitapi.io
Every request needs an X-API-Key header (or the RapidAPI proxy headers, if you route through RapidAPI).
Related pages: Playlist Videos for the ordered video IDs, YouTube Search for discovery.
Request parameters¶
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
query | string | yes | Playlist ID or full playlist/watch URL. Missing → 422. |
The parameter is id, not url
The handler accepts URLs but the parameter name is id. Sending ?url=... yields a FastAPI 422 validation error.
Accepted input forms¶
| Input form | Example |
|---|---|
| Bare playlist ID | PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI |
| Playlist URL | https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI |
Watch URL with list |
https://www.youtube.com/watch?v=a1b2C3d4E5f&list=PLFgquLnL59al… |
Short link with list |
https://youtu.be/a1b2C3d4E5f?list=PLFgquLnL59al… |
ID extraction (extract_playlist_id) matches youtube.com/playlist?list=… first. Anything else that matches ^[A-Za-z0-9_-]{10,}$ is passed through as the raw ID. When a URL carries both v= and list=, the playlist is used and the video id is ignored.
URL-encode URLs in query strings
? and & inside a query value must be percent-encoded. curl -G --data-urlencode, Python params=, and URLSearchParams do this for you.
Response¶
{
"id": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI",
"url": "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI",
"title": "Deep Learning Weekly",
"description": "Papers and talks, one per week.",
"videoCount": 148,
"viewCount": 934211,
"lastUpdated": "Oct 28, 2026",
"channel": {
"name": "Example Channel",
"url": "https://www.youtube.com/@examplechannel"
}
}
| Field | Type | Notes |
|---|---|---|
id |
string | Resolved playlist ID |
url |
string | Canonical playlist URL (https://www.youtube.com/playlist?list=<id>) |
title |
string | Playlist title. May be "" if YouTube's InnerTube header was unavailable |
description |
string | null | Playlist description; usually null (YouTube only exposes it for some playlists) |
videoCount |
integer | null | Stated number of videos |
viewCount |
integer | null | Total playlist views, when YouTube reports them |
lastUpdated |
string | null | Human-readable text as YouTube reports it — not a strict ISO timestamp |
channel |
object | null | {name, url} of the owning channel (id is not populated by this endpoint) |
videoCount is the stated size. Private, deleted, or region-blocked videos still count here but do not appear in /v1/youtube/playlist/videos, so len(videoIds) <= videoCount is normal.
Examples¶
curl¶
curl -G "https://youtube.toolkitapi.io/v1/youtube/playlist" \
--data-urlencode "id=https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI" \
-H "X-API-Key: $YOUTUBE_API_KEY"
Python¶
import httpx
API = "https://youtube.toolkitapi.io"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
def playlist_info(playlist: str) -> dict:
resp = httpx.get(
f"{API}/v1/youtube/playlist",
params={"id": playlist},
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
return resp.json()
info = playlist_info("PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI")
print(info["title"], "—", info["videoCount"], "videos")
if info.get("channel"):
print("by", info["channel"]["name"])
JavaScript¶
const API = "https://youtube.toolkitapi.io";
const HEADERS = { "X-API-Key": "YOUR_API_KEY" };
async function playlistInfo(playlist) {
const qs = new URLSearchParams({ id: playlist });
const res = await fetch(`${API}/v1/youtube/playlist?${qs}`, { headers: HEADERS });
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
return res.json();
}
const info = await playlistInfo("https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI");
console.log(`${info.title} — ${info.videoCount} videos`);
Errors¶
Errors use the Supadata-compatible shape:
{
"detail": {
"error": "not-found",
"message": "Playlist not found",
"details": null,
"documentationUrl": "https://supadata.ai/docs/errors"
}
}
| Status | When |
|---|---|
401 |
Missing or invalid X-API-Key |
422 |
id query parameter missing |
429 |
Rate limit exceeded |
5xx |
Upstream scrape failure or timeout |
A non-existent playlist does not normally raise: the service catches upstream failures and returns a skeleton object with the input echoed as id/url and an empty title. Always check title and videoCount for emptiness before treating a response as valid.
Recommended call pattern
Call /v1/youtube/playlist for display data and /v1/youtube/playlist/videos for processing. Both accept the same id, so resolve once and reuse.