How do I get a YouTube video transcript with an API?
Call GET /v1/youtube/posts/{videoId}/transcript. It returns the caption lines with start and end times in milliseconds, the language, and whether YouTube generated the captions. It also lists every caption language the video offers. Pass language, such as en or es-419, to pick one. Without it you get the track in the spoken language.
The YouTube Data API only downloads captions for videos you have permission to edit. Its captions.download method needs OAuth and costs 200 quota units a call.
Checked October 2026 · request and response run against the API · no affiliate links
curl "https://api.openhandle.dev/v1/youtube/posts/synthvid001/transcript?language=en" \
-H "Authorization: Bearer $OPENHANDLE_API_KEY"import { OpenHandle } from '@openhandle/sdk';
const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_API_KEY! });
const transcript = await openhandle.youtube.post('synthvid001').transcript.get({ language: 'en' });
const text = transcript.data.segments.map(segment => segment.text).join(' ');
console.log(text);{
"platform": "youtube",
"resource": "transcript",
"capturedAt": "2026-10-26T18:33:17Z",
"source": "live",
"data": {
"postId": "synthvid001",
"language": "en",
"languageName": "English",
"isAutoGenerated": false,
"segments": [
{ "start": 0, "end": 2400, "text": "Synthetic caption line 1." },
{ "start": 2500, "end": 4900, "text": "Synthetic caption line 2." }
],
"languages": [
{ "language": "en", "name": "English", "isAutoGenerated": false, "isTranslatable": true },
{ "language": "en", "name": "English (auto-generated)", "isAutoGenerated": true, "isTranslatable": true }
]
}
}Trimmed to two caption lines. The video is in the Test dataset, so you can run it on a free Test key.
Why the YouTube Data API does not work for this
- —Edit permission. captions.download only works when the signed-in user may edit the video. Otherwise it returns 403 forbidden.
- —Google sign-in. An API key is not enough. You need a user to sign in with Google.
- —Quota. Listing caption tracks costs 50 units and downloading one costs 200, out of 10,000 a day.
What you get
- —Timed lines. Each segment has
startandendin milliseconds. Divide by 1,000 to link to that second with&t=. - —Every caption language.
languageslists the tracks the video offers, both uploaded and auto-generated.
Start from a link? Pass any watch, youtu.be, Shorts, or live URL to POST /v1/urls/fetch. It returns the video with its id.
When this does not work
A video without captions is not an error. It answers with an empty segments list, so check languages before you retry.
| Situation | Status | Code |
|---|---|---|
| The video has no captions, or none in that language | 200 | Empty segments |
| The video does not exist | 404 | POST_NOT_FOUND |
| The ID is not a valid YouTube video ID | 400 | INVALID_IDENTIFIER |
{
"error": {
"code": "POST_NOT_FOUND",
"message": "This post was not found.",
"requestId": "req_01m5…",
"retryable": false
}
}Every new workspace starts with 100 free live requests, no card needed.
Read next
More YouTube questions
Send your agent ahead.
Paste the prompt into your agent and it sets everything up. Or come yourself, it takes five minutes.
100 free requests. No card needed.