ToolzerHub
All posts

YouTubeExplainer

YouTube transcript API: what Google allows and how to get a video's transcript as JSON

Google's captions API returns text only for videos you can edit, 250 quota units per transcript. Get a public video's transcript as JSON for 1 credit.

5 min read

Short answer

  • The YouTube Data API v3 has a captions resource, but captions.download needs OAuth and 'permission to edit the video'. One list plus one download costs 250 of the default 10,000 daily quota units.
  • For a video on someone else's channel, the official API returns track metadata and no caption text.
  • ToolzerHub returns timed transcript segments for a public video with captions, from a video ID or URL. 1 credit per call, $0.99 to $1.90 per 1,000 transcripts, 100 free credits a month.
On this page

You want the text of a YouTube video as data: every line with its timestamp, ready to search, summarise or pass to a model. YouTube shows the transcript in the browser, and Google's YouTube Data API has a captions resource. That resource gives caption text only for videos you are allowed to edit.

What the official API gives you

The YouTube Data API v3 has a captions resource with two read methods. captions.list "Returns a list of caption tracks that are associated with a specified video." Google's reference adds: "the API response does not contain the actual captions."

The text comes from captions.download, which takes a track ID from captions.list. It returns the track in its original format or as SRT, VTT, TTML, SBV or SCC. With tlang it returns a machine translation.

Both methods need authorization with the youtube.force-ssl or youtubepartner scope. Google's auth guide says the API "supports the OAuth 2.0 protocol for authorizing access to private user data."

Where it stops

Google's captions.download reference says: "This method requires the user to have permission to edit the video." Its error table lists 403 forbidden: "The permissions associated with the request are not sufficient to download the caption track."

Quota is the second limit. captions.list costs 50 units and captions.download costs 200, so one transcript costs 250 units. A project gets 10,000 units a day for all endpoints except search.list and videos.insert. That is 40 transcripts a day if nothing else uses quota. More needs Google's quota extension request form. Searches come from a separate bucket of 100 calls a day; see the YouTube search API quota.

Get a public video's transcript in one request

ToolzerHub returns the transcript of a public YouTube video as JSON. You need one API key. There is no Google Cloud project, no OAuth and no access to the channel. video_reference takes a video ID or a watch, youtu.be, Shorts or embed URL.

bash
curl "https://api.toolzerhub.com/v2/youtube/transcript?video_reference=M7lc1UVf-VE&language_code=en" \
  -H "x-api-key: $TOOLZERHUB_API_KEY"

Response shape from the API reference, checked 2026-10-08. We have not captured a live response from this endpoint yet, so this shows the documented fields, not real output.

json
{
  "data": {
    "id": "string",
    "transcript": [
      {
        "startMs": "string",
        "endMs": "string",
        "startTime": "string",
        "text": "string"
      }
    ]
  }
}

What the fields mean:

  • transcript is a list of timed segments. Each has the line's text, its startMs and endMs, and a display startTime.
  • The millisecond fields are strings. Convert them to numbers before you do arithmetic.
  • language_code picks the transcript language. There is no cursor: one call returns one video.

Whether a transcript exists depends on the video and its published captions. A call that fails costs nothing.

For an SRT or VTT file, GET /v2/youtube/subtitles lists a video's caption tracks with each track's language and url. Pass that url as caption_source to GET /v2/youtube/subtitle with caption_style=srt or vtt. Add translation_code for a translation. That is 2 calls per video.

What it costs

  • Every call costs 1 credit. One call returns one video's transcript, so 1,000 transcripts is 1,000 credits.
  • Plans start at $29 a month for 20,000 credits ($1.45 per 1,000) and go down to $0.99 per 1,000 on Business; one-time packs start at $19 for 10,000 credits and never expire. That is $0.99 to $1.90 per 1,000 transcripts.
  • The SRT or VTT route is 2 credits per video: $2.22 to $3.80 per 1,000.
  • Failed calls are not charged. Every account gets 100 free credits a month, which is 100 transcripts for testing.

Next step

See the YouTube API page and the YouTube reference, which lists all 29 endpoints under /v2/youtube/. Or get a free API key and run the request above.

Use Google's API for videos you can edit. There it returns the official track list and downloads tracks in five formats. We cannot upload or edit captions; captions.insert (400 units) and captions.update (450 units) can. For a few videos from your own computer, the open-source youtube-transcript-api Python library is free and "does not require an API key nor a headless browser." Its README warns that it "uses an undocumented part of the YouTube API."

Not affiliated with YouTube or Google LLC.

Details

Official API, from Google's reference pages:

  • "All API requests, including invalid requests, incur at least a one-point quota cost."
  • captions.download errors: 403 forbidden, 404 captionNotFound, and 400 couldNotConvert when the requested tfmt or tlang cannot be produced.
  • trackKind is ASR ("generated using automatic speech recognition"), forced or standard.
  • tlang translations use "machine translation, such as Google Translate."

ToolzerHub:

  • caption_style accepts json3, srv1, srv2, srv3, ttml, vtt and srt. Omitted, it is srv1.
  • /v2/youtube/subtitle returns the track as one string in data.
  • For metadata on many videos, GET /v2/youtube/video takes comma-separated video IDs in video_references.
  • Errors come back as { error: { code, status, message, retryable, details } }. An empty balance returns 402 PAYMENT_REQUIRED.

Sources

Get this data from your own code

The YouTube API returns it as JSON with one x-api-key header. 100 free credits monthly.

Get API key(opens in new tab)
See the YouTube API

Keep reading