The whole API in one breath.
The gettranscript.io API exposes one resource: GET /api/get-transcript. You pass a YouTube video ID, you get back a clean transcript in any of six formats. That's the whole product.
Authentication is a single Bearer token. Errors come back in one shape. There are no webhooks, no async jobs, no SDKs to install — just fetch from anything that speaks HTTP.
Prefer a task-oriented walkthrough? The how-to guides cover specific jobs — downloading subtitles, picking between formats, wiring transcripts into your workflow.
A single Bearer token.
Every request needs an Authorization header. Find your key in the Dashboard → API access tab.
Authorization: Bearer YOUR_API_KEYTreat your key like a password. If exposed, regenerate from the dashboard — your old key is invalidated immediately.
GET /api/get-transcript
Returns the transcript for a single video. Idempotent. Cached responses don't refetch from YouTube.
Query parameters
dQw4w9WgXcQ) or any full youtube.com / youtu.be URL — we'll parse out the ID.- Type
- string
- Required
- yes
- Description
- YouTube video ID (e.g.
dQw4w9WgXcQ) or any full youtube.com / youtu.be URL — we'll parse out the ID.
txt, txt_timestamped, srt, vtt, json, md. Omit to receive the full JSON object.- Type
- string
- Required
- no
- Description
- One of
txt,txt_timestamped,srt,vtt,json,md. Omit to receive the full JSON object.
Two shapes: success and error.
Every response is JSON. Successes carry the transcript and your remaining credit balance; errors share one consistent envelope.
{
"success": true,
"cached": false,
"video_id": "dQw4w9WgXcQ",
"text": "Welcome back — today we're walking through…",
"language": "English",
"language_code": "en",
"is_generated": false,
"remaining_credits": 311,
"segments": [
{ "text": "Welcome back…", "start": 0.0, "duration": 4.2 },
{ "text": "The headline change is the API.", "start": 4.2, "duration": 5.1 }
]
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "You have no credits remaining."
}
}Success fields
- Type
- boolean
- Required
- yes
- Description
- Always true for 200 responses.
- Type
- boolean
- Required
- yes
- Description
- Whether this transcript was served from cache. Cached responses still cost 1 credit.
- Type
- string
- Required
- yes
- Description
- The canonical YouTube video ID.
- Type
- string
- Required
- yes
- Description
- The full transcript as one continuous string.
- Type
- array
- Required
- yes
- Description
- Time-aligned segments with start, duration, and text.
- Type
- string
- Required
- no
- Description
- Display name of the transcript track, e.g. "Finnish (auto-generated)". English is preferred; otherwise the video's own language is used.
- Type
- string
- Required
- no
- Description
- ISO language code of the transcript track, e.g. "en" or "fi".
- Type
- boolean
- Required
- no
- Description
- True if the track is auto-generated rather than uploader-provided.
- Type
- number
- Required
- yes
- Description
- Your credit balance after this request was billed.
Six errors to know.
Each error returns the corresponding HTTP status and a stable string code. Build against the code, not the message.
- Code
- UNAUTHORIZED
- Meaning
- Missing, malformed, or invalid API key.
- Code
- INSUFFICIENT_CREDITS
- Meaning
- Your credit balance is 0. Top up to continue.
- Code
- TRANSCRIPT_NOT_FOUND
- Meaning
- No transcript available — disabled by uploader or video unavailable.
- Code
- INVALID_VIDEO_ID
- Meaning
- The videoId query parameter is missing or malformed.
- Code
- RATE_LIMITED
- Meaning
- Too many requests — check the Retry-After header.
- Code
- INTERNAL_ERROR
- Meaning
- Unexpected server error. Try again or write to us.
Drop-in snippets.
Copy any of these into your codebase. Replace YOUR_API_KEY with the value from your dashboard.
curl https://gettranscript.io/api/get-transcript?videoId=dQw4w9WgXcQ \
-H "Authorization: Bearer YOUR_API_KEY"One credit per fetch. Cached forever.
Every successful request — whether served fresh from YouTube or instantly from cache — costs one credit. Errors are free.
Once we've fetched a video, we cache the segments permanently. The same video ID called again uses the cache (still 1 credit, but ~80ms instead of 1–3 seconds). If you'd rather not be billed for cached fetches, dedupe video IDs on your side before calling — your call.
Generous, but not infinite.
The default account ceiling is 60 requests / minute per API key. If you hit a limit, we return 429 with a Retry-After header (seconds). Need more? Email us — we'll lift it.
HTTP/1.1 429 Too Many Requests
Retry-After: 14
Content-Type: application/json
{
"error": {
"code": "RATE_LIMITED",
"message": "Slow down — try again in 14s."
}
}What's changed lately.
Backwards-incompatible changes ship with at least 30 days of notice. Anything else, we just ship.