Social Fetch
Start for freeStart free
YouTube hub

YouTube Playlist API

Resolve a public YouTube playlist by id or playlist URL — title, owner channel, and the video list in the shared Social Fetch envelope.

GET /v1/youtube/playlists

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/youtube/playlists takes a required playlistId query param. Pass a bare playlist id (typically PL…) or a YouTube playlist URL / watch URL that includes a list= parameter; the API coerces the list value when present. On a found lookup you get data.playlist (id, title, owner with handle and channel id when available, totalVideos) and data.videos rows with id, title, url, thumbnail, duration, and uploader channel fields. Branch on data.lookupStatus before you write rows — HTTP 200 alone does not mean the playlist resolved, and found can still return an empty videos array.

Long playlists are paginated: when data.page.hasMore is true, pass data.page.nextCursor as cursor (with the same playlistId) to get the next page. Pages after the first carry videos only, so data.playlist title, owner, and totalVideos are null there. Each page is billed separately.

Bill from meta.creditsCharged. This route is one playlist get. Keyword discovery that returns playlist hits is GET /v1/youtube/search with type=playlists. Single-video detail and transcripts are separate paths under the same YouTube tag and API key.

YouTube Playlist API FAQ

How do I get a YouTube playlist via API?

Call GET /v1/youtube/playlists with your Social Fetch API key (x-api-key) and a playlistId query param. Read data.lookupStatus, then data.playlist, data.videos, and data.page for the next-page cursor. See the API docs for parameters and examples.

What playlist identifiers does the endpoint accept?

A YouTube playlist id, or a public playlist/watch URL that includes a list= query value. URLs without list= are rejected. Pass one playlistId per request.

How much does the YouTube playlist endpoint cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

What does the YouTube playlist response include?

When found: data.playlist (id, title, owner channel fields, totalVideos) and data.videos (id, title, url, thumbnailUrl, durationSeconds, durationText, channelTitle, channelUrl). Always branch on data.lookupStatus first.

Does found always mean the playlist has videos?

No. lookupStatus found means the playlist resolved. data.videos may still be empty. not_found means the playlistId did not resolve (playlist is null and videos is empty). Persist meta.requestId when you need to debug a miss.

How is this different from YouTube search with type=playlists?

This route fetches one known playlist by id or list= URL and returns its summary plus video rows. GET /v1/youtube/search with type=playlists finds playlist matches for a keyword. Search to discover ids; this endpoint to expand a playlist you already have.

Can I get transcripts for every video in the playlist on this route?

No. This endpoint returns playlist metadata and video list rows. For spoken text on a single video, call GET /v1/youtube/videos/transcript with that video's URL after you pull ids from data.videos.

Do I need a Google Cloud project for this endpoint?

No. You authenticate to Social Fetch with an API key. The route reads public playlist data; it does not act on behalf of a logged-in YouTube user.

Other YouTube endpoints