Batch Transcripts

Transcript extraction for a list of videos in one job. Submit up to 20 URLs, get a jobId back immediately, then poll until the job completes. Failed videos never fail the job - each result carries its own status.

Method Endpoint Purpose
POST /v1/youtube/transcript/batch Submit a batch of URLs (returns 202 + jobId)
GET /v1/youtube/transcript/batch/{job_id} Poll job status and retrieve per-video results

For a single video, use GET /v1/youtube/transcript instead - it returns segments synchronously.

Base URL

https://media.toolkitapi.io

Requires an X-API-Key header.

1. Submit a job

curl -X POST "https://media.toolkitapi.io/v1/youtube/transcript/batch" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "https://www.youtube.com/watch?v=9bZkp7q19f0"
    ],
    "lang": "en"
  }'
{"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

Request body

Field Type Default Description
urls string[] required 1-20 YouTube URLs or bare video IDs
lang string null Preferred caption language, e.g. en, de, ja. Falls back to the video's default track

Response

202 Accepted

Field Description
jobId Opaque job identifier used for polling

2. Poll for results

curl "https://media.toolkitapi.io/v1/youtube/transcript/batch/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: YOUR_KEY"
import time
import requests

HEADERS = {"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"}
BASE = "https://media.toolkitapi.io/v1/youtube/transcript/batch"


def batch_transcripts(urls: list[str], lang: str = "en", timeout: float = 180.0) -> dict:
    job_id = requests.post(
        BASE, headers=HEADERS, json={"urls": urls, "lang": lang}, timeout=30
    ).json()["jobId"]

    deadline = time.monotonic() + timeout
    delay = 1.0
    while time.monotonic() < deadline:
        job = requests.get(f"{BASE}/{job_id}", headers=HEADERS, timeout=30).json()
        if job["status"] in {"completed", "failed"}:
            return job
        time.sleep(delay)
        delay = min(delay * 1.5, 5.0)  # gentle backoff

    raise TimeoutError(f"batch job {job_id} still running after {timeout}s")


job = batch_transcripts(
    [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://www.youtube.com/watch?v=9bZkp7q19f0",
    ]
)

for item in job["results"]:
    if item["status"] == "succeeded":
        words = sum(len(seg["text"].split()) for seg in item["content"])
        print(item["id"], item["lang"], f"{words} words")
    else:
        print(item["id"], item["error_code"], item["error"])
const HEADERS = { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" };
const BASE = "https://media.toolkitapi.io/v1/youtube/transcript/batch";

async function batchTranscripts(urls, lang = "en") {
  const submit = await fetch(BASE, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ urls, lang }),
  });
  const { jobId } = await submit.json();

  for (;;) {
    const res = await fetch(`${BASE}/${jobId}`, { headers: HEADERS });
    const job = await res.json();
    if (job.status === "completed" || job.status === "failed") return job;
    await new Promise((r) => setTimeout(r, 2000));
  }
}

A 2-second poll interval is plenty; these jobs finish in seconds for short videos. Do not poll faster than once per second.

Response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "results": [
    {
      "id": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "status": "succeeded",
      "lang": "en",
      "content": [
        {"text": "We're no strangers to love", "offset": 0.0, "duration": 3.4, "lang": "en"},
        {"text": "You know the rules and so do I", "offset": 3.4, "duration": 3.1, "lang": "en"}
      ]
    },
    {
      "id": "not-a-video",
      "url": "not-a-video",
      "status": "failed",
      "error_code": "invalid-request",
      "error": "Could not parse video ID from: not-a-video"
    }
  ],
  "stats": {"total": 2, "succeeded": 1, "failed": 1},
  "completedAt": "2026-10-17T04:12:09.331Z"
}
Field Description
jobId Job identifier
status queued, active, completed, or failed
results Per-video outcomes; [] while queued/active
results[].id Video ID (or the raw input, when unparseable)
results[].url Canonical video URL
results[].status succeeded or failed
results[].content Timed segments - present only on success
results[].lang Language the transcript was fetched in
results[].error_code invalid-request or transcript-not-found
results[].error Human-readable failure reason
stats Aggregate counts, present once results exist
completedAt ISO-8601 completion timestamp

Segment shape

Each segment in content is:

{"text": "...", "offset": 12.7, "duration": 2.9, "lang": "en"}

offset and duration are in seconds (floats, not HH:MM:SS). To build a timestamped SRT or readable transcript:

def to_srt(segments: list[dict]) -> str:
    def stamp(sec: float) -> str:
        h, rem = divmod(int(sec), 3600)
        m, s = divmod(rem, 60)
        return f"{h:02}:{m:02}:{s:02},000"

    lines = []
    for idx, seg in enumerate(segments, start=1):
        start = seg["offset"]
        lines.append(f"{idx}\n{stamp(start)} --> {stamp(start + seg['duration'])}\n{seg['text']}\n")
    return "\n".join(lines)

Behaviour to know

  • No transcript ≠ job failure. Videos without captions come back as failed with error_code: transcript-not-found (404 semantics) while the job still reports completed.
  • Language fallback. If lang is unavailable, the service returns whatever track the video has and reports the actual language in results[].lang. Check it before assuming.
  • Job expiry. Jobs are kept in memory with a TTL - poll promptly, and persist results once you have them. A 404 on the status endpoint means the job expired or never existed.
  • No retries inside the batch. A failed item is not retried; resubmit just those URLs if you want another attempt.

Errors

Status Meaning
202 Job accepted
401 Missing or invalid X-API-Key
404 Unknown or expired job_id
422 Body validation - empty urls or more than 20 entries
  • GET /v1/youtube/transcript - single-video, synchronous transcript endpoint
  • GET /v1/youtube/video - titles, stats, and tags for the same videos
  • Media Conversion - transcode the downloaded video to audio