---
title: "Get YouTube transcript (v2)"
method: GET
path: "/api/v2/youtube/transcript"
tags: ["YouTube transcript"]
---

# Get YouTube transcript (v2)

`GET /api/v2/youtube/transcript`

Get a YouTube video's transcript — pass a video URL or 11-character ID as `video_url`.

By default you get English, or the video's first available language if there's no English.

To choose a language, set `language` to a comma-separated list in priority order; we return the first one that's available. Example: `language=de,en,asr` tries German, then English, then the auto-generated captions.

- `asr` = the video's auto-generated captions (ASR = automatic speech recognition).
- `asr-<code>` = auto-generated captions in a specific language, e.g. `asr-hi`.
- A plain code like `hi` returns the human-made captions if they exist, otherwise the auto-generated ones (`asr-hi`).
- Language codes ignore region (`de` matches `de-DE`) and are case-insensitive. Up to 10 codes.

The `language` field in the response always tells you exactly what you got. Tip: call GET /api/v2/youtube/info first (it's free) to see which languages a video offers.

## Query parameters

- `video_url` string, required — YouTube video URL or bare 11-char ID
- `language` string, nullable — Optional comma-separated language priority list (e.g. `de,en,asr`). Omit it to get English, or the video's first available language. We return the first code that's available. `asr` = auto-generated captions; `asr-<code>` = a specific auto language (e.g. `asr-hi`). Codes ignore region (`de` matches `de-DE`). The response's `language` field tells you exactly what you got — ask for `hi` and you'll see `asr-hi` if only auto captions exist.
- `send_metadata` boolean — Include basic video metadata in response
- `format` 'json' | 'text' — Available transcript formats for v2 (restricted).
- `include_timestamp` boolean — Include timestamps in transcript output

## Response `200`

Transcript retrieved successfully

- APITranscriptResponseV2 — Public API response for v2 with a simplified contract. - When format=json, `transcript` is a list of segments (with or without timestamps). - When format=text, `transcript` is a plain string (with or without timestamps). - `metadata` is returned only when requested via send_metadata=true. - `length_seconds` / `lengthText` give the total video length; they are `null` when the source doesn't expose a fixed length (e.g. live streams).
  - `video_id` string, required — YouTube video ID
  - `language` string, required — Language of the returned transcript
  - `transcript` union, required
    - TranscriptSegment[]
      - `text` string, required
      - `start` number, required
      - `duration` number, required
    - TranscriptSegmentTextOnly[]
      - `text` string, required
    - string
  - `metadata` AppApiV2YoutubeSchemasMetadata
    - `title` string, nullable
    - `author_name` string, nullable
    - `author_url` string, nullable
    - `thumbnail_url` string, nullable
  - `length_seconds` integer, nullable — Total video length in whole seconds (e.g. 213). null when the source doesn't expose a fixed length — live streams and the rare fallback extraction path.
  - `lengthText` string, nullable — Total video length as a human-readable string, e.g. '3:33' or '1:02:45'. null in the same cases as length_seconds. Matches the lengthText format used by the search/channel/playlist endpoints.

## Other responses

- `401` — Unauthorized - invalid Authorization format or API key
- `402` — Payment Required - inactive plan or exhausted credits
- `404` — **Not Found** - Video doesn't exist or no transcript available. **Do not retry.** When `language` was provided (Mode B), the body also includes a machine-readable `code` and an `available_languages` list so the caller can retry with a language that exists.
- `408` — **Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).
- `422` — **Validation Error** - Invalid YouTube URL or video ID format. **Do not retry** with the same input.
- `429` — **Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.
- `500` — **Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.
- `503` — **Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.

---

[API](https://skmtc.dev/transcriptapi/apis/youtube-transcript-api-public.md) · [All operations](https://skmtc.dev/transcriptapi/apis/youtube-transcript-api-public/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/transcriptapi/youtube-transcript-api-public/revisions/3203c2d6486c/schema)