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

Create a YouTube video metadata batch job

Creates an asynchronous batch job to retrieve metadata 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.

4 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

4 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
404Returned when a referenced playlist or channel cannot be found; 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. A 404 is returned when a referenced playlist or channel cannot be found, and a 500 is returned when an internal error occurs.