Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supadata.ai/llms.txt

Use this file to discover all available pages before exploring further.

The batch endpoints allow you to process multiple YouTube videos in a single request. This is useful for analyzing entire playlists or channels, or for processing a list of videos. Batch operations are asynchronous and return a job ID that can be used to check the results.
This feature is available only on paid plans.

​
Supported Source Types

All batch endpoints support the following source types:
  • List of video URLs or IDs
  • Playlist URL or ID
  • Channel URL, handle, or ID

​
Batch Endpoints

​
Transcript Batch

​
Request

import {
  Supadata,
} from '@supadata/js';
// Initialize the client
const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});

// Start a YouTube transcript batch job
const transcriptBatch = await supadata.youtube.transcript.batch({
  videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],
  // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively
  // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
  lang: 'en',
});
console.log(`Started transcript batch job: ${transcriptBatch.jobId}`);

​
Parameters

ParameterTypeRequiredDescription
videoIdsarrayOne of these is requiredArray of YouTube video IDs or URLs
playlistIdstringOne of these is requiredYouTube playlist URL or ID
channelIdstringOne of these is requiredYouTube channel URL, handle or ID
limitnumberNoMaximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000
langstringNoPreferred language code for transcripts (ISO 639-1)
textbooleanNoWhen true, returns plain text transcript. Default: false

​
Response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000"
}

​
Video Metadata Batch

​
Request

import {
  Supadata,
} from '@supadata/js';
// Initialize the client
const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});

// Start a YouTube video metadata batch job
const videoBatch = await supadata.youtube.video.batch({
  playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc',
  limit: 20,
  // videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'] // alternatively
  // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
});
console.log(`Started video metadata batch job: ${videoBatch.jobId}`);

​
Parameters

ParameterTypeRequiredDescription
videoIdsarrayOne of these is requiredArray of YouTube video IDs or URLs
playlistIdstringOne of these is requiredYouTube playlist URL or ID
channelIdstringOne of these is requiredYouTube channel URL, handle or ID
limitnumberNoMaximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000

​
Response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000"
}

​
Getting Batch Results

Once you’ve created a batch job, you can check its status and retrieve results using the job ID.

​
Check Batch Job Status

GET /v1/youtube/batch/{jobId} - Get the status and results of a batch job.

​
Parameters

ParameterTypeRequiredDescription
jobIdstringYesThe ID of the batch job

​
Request

import { Supadata } from "@supadata/js";

const supadata = new Supadata("YOUR_API_KEY");

// Check the status of a batch job
const batchResult = await supadata.youtube.batch.getJobStatus(jobId);

if (batchResult.status === "completed") {
  console.log("Batch job completed successfully!");
  console.log(`Total videos: ${batchResult.stats.total}`);
  console.log(`Succeeded: ${batchResult.stats.succeeded}`);
  console.log(`Failed: ${batchResult.stats.failed}`);
  
  // Process each result
  batchResult.results.forEach((result, index) => {
    if (result.transcript) {
      console.log(`Video ${index + 1}: ${result.videoId}`);
      console.log(`Transcript: ${result.transcript.content}`);
      console.log(`Language: ${result.transcript.lang}`);
    } else if (result.errorCode) {
      console.log(`Video ${index + 1} failed: ${result.errorCode}`);
    }
  });
} else if (batchResult.status === "failed") {
  console.error("Batch job failed:", batchResult.error);
} else {
  console.log("Job status:", batchResult.status);
}

​
Response

{
  "status": "completed",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "transcript": {
        "content": "Never gonna give you up, never gonna let you down...",
        "lang": "en",
        "availableLangs": ["en", "es", "fr"]
      }
    },
    {
      "videoId": "xvFZjo5PgG0",
      "errorCode": "transcript-unavailable"
    }
  ],
  "stats": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  },
  "completedAt": "2025-04-03T06:59:53.428Z"
}

​
Batch Job Status

The batch job can be in one of the following states:
StatusDescription
queuedThe job is in the queue waiting to be processed
activeThe job is currently being processed
completedThe job has finished processing all videos
failedThe job failed due to an error
Batch jobs are processed asynchronously and may take some time to complete, especially for large playlists or channels. You should poll the job status endpoint until the status is either “completed” or “failed”.

​
Pricing

  • 1 request to start a batch job = 1 credit
  • 1 video / transcript in a batch = 1 credit
For example, if you start a batch job with 10 videos, you will be charged 11 credits: 1 for the request and 10 for the videos.