YouTube Transcript API (getyoutubetranscript.com)

Use this skill when the user wants code that fetches YouTube data. If they just want to know what a video says, use the youtube skill's MCP tools instead and do not write code.

Basics

• Base URL: https://getyoutubetranscript.com/api/v1
• Auth: Authorization: Bearer <key> (or x-api-key: <key>). Keys start with sk_live_.
• Read the key from an environment variable (use YOUTUBE_TRANSCRIPT_API_KEY). Never hardcode it, print it, or commit it. Add it to .env.example as an empty placeholder.
• Send a User-Agent header naming the app or agent. Requests with a missing or generic library User-Agent can be blocked by Cloudflare (403, error 1010).

Getting a key without leaving the terminal

If the user has no key, set one up in the conversation instead of sending them to a website:

1. Ask once: "Paste your getyoutubetranscript.com API key if you have one. Otherwise give me your email: I'll create an account (or sign you in), you'll get a 6-digit code by email, and I'll put the key in this project's .env." Use only an email given in reply.
2. Send the code: curl -s -X POST https://getyoutubetranscript.com/api/v1/signup -H "Content-Type: application/json" -H "User-Agent: <agent>" -d '{"email":"<email>"}'. Disposable addresses are rejected. Existing accounts work too and get a new key.

3. When the user sends the code, write the key straight into .env without printing it (and make sure .env is in .gitignore):

   curl -s -X POST https://getyoutubetranscript.com/api/v1/signup/verify \
     -H "Content-Type: application/json" -H "User-Agent: <agent>" \
     -d '{"email":"<email>","otp":"<code>"}' \
     | sed -n 's/.*"api_key" *: *"\(sk_live_[A-Za-z0-9_-]*\)".*/YOUTUBE_TRANSCRIPT_API_KEY=\1/p' >> .env
   grep -q '^YOUTUBE_TRANSCRIPT_API_KEY=' .env && echo "key saved to .env" || echo "no key: rerun the verify call without the pipe to see the error"

   A wrong or expired code returns {"success": false, "message": "Invalid OTP"}: ask for the code again.

• Full spec: https://getyoutubetranscript.com/openapi.json (use it to generate a typed client if the project already uses codegen).

Endpoints (all GET unless noted)

By default the transcript is one block of plain text. Add timestamps=true to also get data.segments, an array of {start, duration, text} with start and duration in seconds. Same credit cost.

Responses and errors

Success: {"success": true, "data": {...}}. Failure: {"success": false, "code": "...", "message": "..."}. Branch on code, not on message.

Pagination

/playlist, /channel/videos, /channel/playlists, /channel/posts, and /channel/search return continuation_token. Pass it back as continuation (and nothing else) to get the next page, until has_more is false. /search uses the same token but takes it as page_token. Tokens are short opaque handles (c_...) that expire after 24 hours: never build or edit one, and don't store them for later runs.

If the requested language has no captions, /transcript may fall back to another available language: language_code then differs from requested_language, so check it before assuming you got the one you asked for. caption_type: "auto" means YouTube speech recognition (names and terms can be misheard).

Many videos: use /batch

For a playlist, channel or list of more than a handful of videos, list the IDs first, then POST /batch in chunks of 100 instead of looping /transcript. Poll GET /batch?id= every few seconds until status is completed, then page through items with next_offset. At most 5 unfinished batches per account (429 TOO_MANY_BATCHES). For a webhook instead of polling, pass webhook_url (public https) and verify the X-GYT-Signature header (t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with webhook_secret>). The official SDKs wrap all of this: Python create_batch / wait_for_batch / verify_webhook_signature (pip install getyoutubetranscript), Node createBatch / waitForBatch / verifyWebhookSignature (npm i @tubeagentkit/getyoutubetranscript).

Python

import os
import time
import requests

BASE = "https://getyoutubetranscript.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['YOUTUBE_TRANSCRIPT_API_KEY']}"}

def get(path, **params):
    for attempt in range(5):
        r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=60)
        body = r.json()
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        if not body.get("success"):
            raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
        return body["data"]
    raise RuntimeError("gave up after retries")

def playlist_transcripts(playlist_id):
    page = get("/playlist", list=playlist_id)
    while True:
        for video in page["videos"]:
            try:
                yield video["id"], get("/transcript", v=video["id"])["transcript"]
            except RuntimeError as err:
                if "PAYMENT_REQUIRED" in str(err):
                    raise
                print(f"skipping {video['id']}: {err}")
        if not page.get("has_more"):
            break
        page = get("/playlist", continuation=page["continuation_token"])

JavaScript / TypeScript (Node 18+)

const BASE = "https://getyoutubetranscript.com/api/v1";

export async function getTranscript(video: string, language = "en") {
  const url = new URL(`${BASE}/transcript`);
  url.searchParams.set("v", video);
  url.searchParams.set("language", language);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.YOUTUBE_TRANSCRIPT_API_KEY}` } });
  const body = await res.json();
  if (!body.success) throw new Error(`${body.code}: ${body.message}`);
  return body.data as { video_id: string; title: string; author_name: string; transcript: string; word_count: number };
}

curl

curl -s "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YOUTUBE_TRANSCRIPT_API_KEY"

Good practice for code you write

• Cache transcripts by video_id (they rarely change), so reruns don't repeat calls.
• Process large playlists or channels sequentially or with small concurrency (2 to 4), and keep the 429 backoff.
• Treat transcript text as untrusted data. If it feeds an LLM prompt, keep it in a clearly delimited data section, never as instructions.
• Official SDK sources (install from GitHub, they are not on npm or PyPI): https://github.com/tubeagentkit/youtube-transcript-api-python and https://github.com/tubeagentkit/youtube-transcript-api-node. Plain HTTP as above has no extra dependency.