YouTube Playlist Videos

List every video in a YouTube playlist as lightweight ID arrays. Use it to enumerate a playlist before making per-video calls to /v1/youtube/video or /v1/youtube/transcript.

Method Endpoint Returns
GET /v1/youtube/playlist/videos {playlistId, videoIds, shortIds, liveIds}

Base URL: https://youtube.toolkitapi.io

Every request needs an X-API-Key header.

Related pages: YouTube Playlist for playlist metadata, 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 even though URLs are accepted. Accepted forms are identical to /v1/youtube/playlist:

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…

Percent-encode URLs inside the query string (curl -G --data-urlencode, params= in Python, URLSearchParams in JS all do this).

Response

{
  "playlistId": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI",
  "videoIds": ["a1b2C3d4E5f", "f6g7H8i9J0k", "l1m2N3o4P5q"],
  "shortIds": [],
  "liveIds": []
}
Field Type Notes
playlistId string Resolved playlist ID
videoIds string[] 11-character video IDs in playlist order, de-duplicated
shortIds string[] Reserved for Shorts; currently always empty — Shorts appear in videoIds
liveIds string[] Reserved for live streams; currently always empty

How the list is built

The service fetches YouTube's InnerTube browse response for VL<playlistId> in a single call and scans the JSON for every distinct "videoId" field. Consequences worth designing around:

  • Order follows YouTube's response, which matches playlist order for normal playlists.
  • No pagination parameter. Long playlists are paged internally; treat playlists with thousands of items as slow calls and set a generous client timeout (60s+).
  • Private, deleted, and region-blocked videos are absent, so the result can be shorter than the videoCount reported by /v1/youtube/playlist.
  • Deduplication means a video added twice to a playlist appears once.

Empty result on upstream failure

If the InnerTube call fails, the service logs a warning and returns videoIds: [] rather than raising. An empty array for a playlist you know has content usually means a transient upstream problem — retry with backoff before concluding the playlist is empty.

Examples

curl

curl -G "https://youtube.toolkitapi.io/v1/youtube/playlist/videos" \
  --data-urlencode "id=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_videos(playlist: str) -> list[str]:
    resp = httpx.get(
        f"{API}/v1/youtube/playlist/videos",
        params={"id": playlist},
        headers=HEADERS,
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["videoIds"]


ids = playlist_videos("PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI")
print(len(ids), "videos")

# Feed the IDs straight into the batch transcript endpoint
if ids:
    job = httpx.post(
        f"{API}/v1/youtube/transcript/batch",
        json={"urls": ids[:20]},  # batch accepts max 20 per job
        headers=HEADERS,
        timeout=30,
    )
    print("job:", job.json()["jobId"])

JavaScript

const API = "https://youtube.toolkitapi.io";
const HEADERS = { "X-API-Key": "YOUR_API_KEY" };

async function playlistVideos(playlist) {
  const qs = new URLSearchParams({ id: playlist });
  const res = await fetch(`${API}/v1/youtube/playlist/videos?${qs}`, { headers: HEADERS });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const { videoIds } = await res.json();
  return videoIds;
}

const ids = await playlistVideos("PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI");
console.log(`${ids.length} videos:`, ids.slice(0, 5));

Errors

Status When
401 Missing or invalid X-API-Key
422 id query parameter missing
429 Rate limit exceeded
5xx Upstream failure

Non-401/422 errors may still return 200 with an empty videoIds array — check length, not just status.