Prospect demo — Supadata (unofficial)
POST/youtube/transcript/batch

Create a YouTube transcript batch job

Creates an asynchronous batch job to retrieve transcripts for multiple YouTube videos. Supply videoIds, playlistId, or channelId to select the videos; playlist- and channel-based batches include regular videos only, skipping Shorts and live streams.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields

Optional batch configuration. Provide one of videoIds, playlistId, or channelId to select the videos to process.

videoIdsarray<string>required
Array of YouTube video IDs or URLs
playlistIdstringoptional
YouTube playlist URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).
channelIdstringoptional
YouTube channel URL, handle or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).
limitnumberoptional
Maximum number of videos to process (when using playlistId or channelId)
Default:10
langstringoptional
Preferred language code of the transcript (ISO 639-1). If not provided, the first available language will be returned. If the requested language is unavailable, the API defaults to the first available language. See [Languages](https://docs.supadata.ai/youtube/supported-language-codes).
textbooleanoptional
When true, returns plain text transcript.
Default:false

3 status codes
200Returns the created batch job's `jobId` for retrieving its status and results.
jobIdstringrequired
The ID of the job
400Returned when the request is invalid, including when none of `videoIds`, `playlistId`, or `channelId` is provided, or when `limit` is outside its allowed range; the response includes an error code, message, and details.
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
500Returned when an internal error occurs; the response includes an error code, message, and details.
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation

Error handling

A 400 is returned when the request is invalid; provide at least one of videoIds, playlistId, or channelId. When using a playlist or channel, limit must be between 1 and 5000; text defaults to false, and an unavailable requested transcript language falls back to the first available language. A 500 is returned when an internal error occurs.