YouTube Transcript API

Get a transcript with one request

Send POST https://tubetranscript.io/api/v1/extract with an Authorization: Bearer header and a JSON body. url is any YouTube video link (watch, youtu.be, shorts, embed or live), up to 2,048 characters. The optional features array asks for hooks, mindmap and action_items in the same call. Set your client timeout to 300 seconds.

import os, time, requests

def get_transcript(video_url):
    api_key = os.environ['TUBETRANSCRIPT_API_KEY']
    while True:
        r = requests.post(
            'https://tubetranscript.io/api/v1/extract',
            headers={'Authorization': f'Bearer {api_key}'},
            json={'url': video_url},
            timeout=300,
        )
        body = r.json()
        if r.status_code == 202:  # audio transcription still running
            time.sleep(int(r.headers.get('Retry-After', 60)))
            continue  # send the same request again
        if not body['success']:
            raise RuntimeError(body['error']['code'])
        return body['data']

data = get_transcript('https://www.youtube.com/watch?v=jNQXAC9IVRw')
print(data['transcript']['text'])

async function getTranscript(videoUrl) {
  while (true) {
    const res = await fetch('https://tubetranscript.io/api/v1/extract', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TUBETRANSCRIPT_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url: videoUrl }),
      signal: AbortSignal.timeout(300000),
    });
    const body = await res.json();
    if (res.status === 202) {
      // audio transcription still running: wait, then send the same request again
      const seconds = Number(res.headers.get('Retry-After') ?? 60);
      await new Promise(resolve => setTimeout(resolve, seconds * 1000));
      continue;
    }
    if (!body.success) throw new Error(body.error.code);
    return body.data;
  }
}

const data = await getTranscript('https://www.youtube.com/watch?v=jNQXAC9IVRw');
console.log(data.transcript.text);

Response fields

Every response, success or error, has the same envelope: success, data and error (code, message). On success, data holds:

Videos without captions

1. The API first reuses your team's job for the same video, then reads the video's captions, which takes seconds.
2. When there are no captions, it transcribes the audio with Whisper. That can take minutes.
3. If transcription is still running when the request runs out of time, you get 202 EXTRACTION_IN_PROGRESS with Retry-After: 60. Send the same request again: it resumes that job, so nothing is transcribed twice.
4. On Pro, audio transcription handles videos up to 2 hours. Private and removed videos, and live streams in progress, fail.

Not writing code? Get a transcript of a video without captions in the browser, or read why a transcript is not available.

Authentication and limits

Already on Pro? Manage your keys in the dashboard. Key handling and limits in detail: security and rate limits.

Errors

Branch on error.code, not on the message text. Only 202 and 502 carry a non-null data.

The full API reference lists every field and code.

Use it in n8n, Make and MCP

• n8n: call the endpoint from an HTTP Request node with a 300 s timeout, enable Settings → Never Error and branch on success.
• Make: set Evaluate all states as errors to No, then branch on success.
• Claude and Cursor: connect the MCP server with the same Pro key; it exposes a get_transcript tool. See the MCP setup.

New to the API? The quickstart covers the first request end to end.

Compared with the youtube-transcript-api Python library

youtube-transcript-api is a Python library you run yourself. It is a good fit when you work from your own machine or already run a proxy.

FAQ