Fetch a transcript

Fetch one transcript synchronously and return it in the requested format. A successful response costs 1 credit.

GET/api/v1/transcript/:videoId

Path parameters

Name	Type	Description
`videoId`required	`string`	Exactly 11 characters matching `[a-zA-Z0-9_-]`.

Query parameters

Name	Type	Description
`lang`	`string`	Preferred language code (e.g. `en`, `es`, `de`). If absent, the default caption track is returned. If the requested language has no track, the request returns `404` and the message lists the codes that are available. A regional code matches its base language, so `en` can return an `en-US` track; the `language` field tells you which one was served.
`format`	`string`	One of `json` (default), `txt`, `srt`, `csv`, `docx`, `markdown`. See Export formats for shape details.

Request

bash

curl -H "Authorization: Bearer yvt_live_..." \
  "https://api.youtubevideotranscript.io/api/v1/transcript/dQw4w9WgXcQ"

JSON response (default)

Content-Type: application/json

json

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 0.08, "duration": 3.28 },
    { "text": "You know the rules and so do I", "start": 1.64, "duration": 4.28 }
  ],
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author_name": "Rick Astley",
    "author_url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
    "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "duration_seconds": 213
  },
  "is_auto_generated": false,
  "available_tracks": [
    { "language_code": "en", "language_name": "English", "is_auto_generated": false, "vss_id": "..." }
  ]
}

Field guarantees

video_id and language are always strings.
transcript is always an array of segment objects.
metadata may be absent if YouTube did not supply enough video details. When present, title, author_name, author_url, and thumbnail_url are strings.
metadata.channel_id and metadata.duration_seconds are populated when available; they may be absent for some videos.
is_auto_generated and available_tracks are present when YouTube exposes them; they may be absent.

A segment always has text; start and duration may be absent when timing is unavailable.

Details and comments

Check caption availability without spending credits using GET /video/:videoId. It also provides views, description, tags, and optional dates and likes, which are not in this transcript response. To fetch comments, call GET /comments/:videoId separately. This REST endpoint does not accept include_comments; that convenience flag belongs to the MCP transcript tool.

Non-JSON formats

With ?format=txt, ?format=srt, ?format=csv, ?format=docx, or ?format=markdown, the response is the raw file with the appropriate Content-Type and Content-Disposition: attachment; filename="<videoId>.<ext>".

bash

# Save as <videoId>.txt
curl -OJ -H "Authorization: Bearer yvt_live_..." \
  "https://api.youtubevideotranscript.io/api/v1/transcript/dQw4w9WgXcQ?format=txt"

# Save as <videoId>.md
curl -OJ -H "Authorization: Bearer yvt_live_..." \
  "https://api.youtubevideotranscript.io/api/v1/transcript/dQw4w9WgXcQ?format=markdown"

Errors

Status	Type	When
400	`bad_request`	`videoId` not 11 characters matching `[a-zA-Z0-9_-]`, or invalid `format` value
402	`insufficient_quota`	Not enough credits
403	`forbidden`	Video unavailable, age-restricted, geo-blocked, or live-stream offline. Can also be temporary, so retry once before treating it as permanent
404	`not_found`	No captions found, or no track matching the requested language

Global 401, 429, and 5xx also apply. See Errors.