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
videoCountreported 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.