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.