SignalYouTube · playlist
Read videos from a public YouTube playlist. GET /api/v1/youtube/playlist accepts your x-api-key header. Production live requests are disabled pending source and commercial-use authorization, including cross-channel use.
Request parameters
Returns public playlist metadata and listed video cards. Pass the returned continuationToken unchanged with the same playlist_id for more results. Unavailable and private video details are not fetched.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlist_id | string | Yes | Public YouTube playlist ID. |
continuationToken | string | No | Opaque SignalShelf cursor from the previous response. Keep the same playlist_id. |
freshness | string | No | 24h (default), 1h, 7d, or live. Accepted cache hits are free; live forces refresh except simultaneous requests may share newly fetched data. |
Code examples
Set SIGNALSHELF_BASE_URL and SIGNALSHELF_API_KEY on your server.
curl "$SIGNALSHELF_BASE_URL/api/v1/youtube/playlist?playlist_id=PLF98rxtslw6s" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/youtube/playlist?playlist_id=PLF98rxtslw6s", {
headers: { 'x-api-key': process.env.SIGNALSHELF_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data, body.meta);import os, requests
response = requests.get(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/youtube/playlist?playlist_id=PLF98rxtslw6s",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
Playlist responses contain a title, source video-count label, and the public videos visible on the playlist page. Each video includes its ID, title, playlist link, thumbnail, duration label, and channel when the page exposes those fields.
The signed continuationToken is bound to playlist_id. YouTube can advertise a cursor even when a later request returns no additional videos; the token does not guarantee a complete listing. Private, deleted, age-gated, or otherwise inaccessible video details are not fetched.
The response contains data and meta. data includes platform, resource, sample:false, provider, and the public source payload. Lists return data.items; individual resources return data.data.
A playlist lookup returns data.title, video_count, and data.videos. Pass continuationToken with the same playlist_id when present. The source may return an empty next page even when it supplied a token; completeness is not guaranteed.
meta includes event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms. A fresh successful result costs one credit; accepted cached results and failures cost zero.
Availability and failures
Implementation is not a continuous availability guarantee. Source rate limits, retention, deleted content, restrictions, and regional availability apply. This is an independent SignalShelf contract, not a drop-in competitor response format.
400: invalid parameters. 401: missing/revoked key. 402: insufficient credits. 404: missing public resource. 429: SignalShelf throttle. 502/503: upstream failure or rate limit, with credit restored.