Social Fetch
Get API key
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 per successful request.

Try in playgroundFull API docs

About this endpoint

Course catalogs, music series, and brand "watch next" lists often live as a single playlist URL someone dropped in Slack. Your pipeline needs the playlist title, who owns it, and the video ids in order — without scraping the playlist page HTML every time YouTube changes the client.

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

Pricing is on the credit badge for this operation; 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 and data.videos. Full parameters and examples are in the API docs.

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