API Documentation

A REST API for YouTube transcripts, search, and metadata. Get an API key from your dashboard — 100 free credits, no card required.

Authentication

Pass your API key as a bearer token, or via x-api-key:

Authorization: Bearer sk_live_...
# or
x-api-key: sk_live_...

Base URL

https://getyoutubetranscript.com/api/v1

Credits & plans

Plan	Price	Credits/mo	Top-up price	Rate limit
Free	$0/mo	100 (one-time)	—	60 req/min
Monthly	$5/mo	1,000	$2.50 / 1,000	200 req/min
Annual	$4.50/mo ($54/yr)	1,000	$1.50 / 1,000	300 req/min
Starter	$19/mo	7,500	$1.50 / 1,000	300 req/min
Pro	$49/mo	25,000	$1.50 / 1,000	400 req/min
Scale	$99/mo	60,000	$1.50 / 1,000	600 req/min

1 credit = 1 successful request. Failed requests are never charged. Example: 10 transcript requests where 2 videos have no captions cost 8 credits, and retrying a failed video costs nothing until it succeeds. Top-up credits expire 30 days from purchase or at the end of your current billing period, whichever is later, and require an active subscription to spend.

Endpoints

GET/transcript1 credit

Get the transcript for a YouTube video, with metadata (title, channel, thumbnail). Also returns language_code vs requested_language, caption_type (manual or auto, null if unknown), and cached / fetched_at.

Parameter	Required	Description
`v`	Yes	Video ID or full YouTube URL
`language`	No	Language code (default: en)
`timestamps`	No	Set to true to add per-line timestamps (segments: start, duration, text in seconds). Off by default.
`translate`	No	Language code to machine-translate into, e.g. es or zh-CN. Timestamps stay aligned; the response adds translated_to. Same 1 credit.

Request

curl "https://getyoutubetranscript.com/api/v1/transcript?v=jNQXAC9IVRw" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "video_id": "jNQXAC9IVRw",
    "language_code": "en",
    "requested_language": "en",
    "caption_type": "manual",
    "title": "Me at the zoo",
    "author_name": "jawed",
    "author_url": "https://www.youtube.com/channel/UC4Qob...",
    "thumbnail_url": "https://...",
    "transcript": "All right, so here we are...",
    "word_count": 39,
    "cached": true,
    "fetched_at": "2026-09-20T03:10:58.938Z"
  }
}

GET/transcript/languages1 credit

List the caption languages a video offers (manual and auto-generated) before fetching one. default_language_code is what /transcript returns with no language; a video with captions turned off returns an empty list.

Parameter	Required	Description
`v`	Yes	Video ID or full YouTube URL

Request

curl "https://getyoutubetranscript.com/api/v1/transcript/languages?v=kJQP7kiw5Fk" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "video_id": "kJQP7kiw5Fk",
    "default_language_code": "en",
    "languages": [
      { "language_code": "en", "name": "English - en", "caption_type": "manual" },
      { "language_code": "es", "name": "Spanish", "caption_type": "manual" }
    ]
  }
}

POST/batch1 credit / successful video

Queue up to 100 videos in one call. Returns a batch_id at once and fetches the transcripts in the background. Poll GET /batch, or pass webhook_url to get a signed POST (X-GYT-Signature header) when it finishes. Failed videos are never charged.

Parameter	Required	Description
`videos`	Yes	Array of video IDs or URLs (1-100). Duplicates are fetched once.
`language`	No	Language code for every video (default: en)
`timestamps`	No	true to include per-line segments in the results
`webhook_url`	No	Public https URL notified when the batch finishes
`Idempotency-Key`	No	Header. Retry the request safely: the same key returns the original batch.

Request

curl -X POST "https://getyoutubetranscript.com/api/v1/batch" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "videos": ["jNQXAC9IVRw", "https://youtu.be/dQw4w9WgXcQ"],
        "webhook_url": "https://example.com/hooks/transcripts"
      }'

Response

{
  "success": true,
  "data": {
    "batch_id": "324eb615-e4d5-4b3c-b8e7-04235671066b",
    "status": "queued",
    "total": 2,
    "succeeded": 0,
    "failed": 0,
    "pending": 2,
    "results_url": "https://getyoutubetranscript.com/api/v1/batch?id=324eb615-...",
    "webhook_secret": "whsec_..."
  }
}

GET/batchFree

Batch status, counts and a page of results in submission order. Succeeded items have the same fields as /transcript; failed items carry an error_code.

Parameter	Required	Description
`id`	Yes	The batch_id from POST /batch
`offset`	No	Items to skip (default: 0)
`limit`	No	Items per page, 1-50 (default: 20)

Request

curl "https://getyoutubetranscript.com/api/v1/batch?id=324eb615-e4d5-4b3c-b8e7-04235671066b" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "batch_id": "324eb615-...",
    "status": "completed",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "credits_charged": 1,
    "items": [
      { "position": 0, "status": "succeeded", "charged": true, "video_id": "jNQXAC9IVRw", "caption_type": "manual", "transcript": "All right, so here we are...", ... },
      { "position": 1, "status": "failed", "charged": false, "video_id": "dQw4w9WgXcQ", "error_code": "TRANSCRIPT_DISABLED" }
    ],
    "next_offset": null
  }
}

GET/search1 credit / page

Search YouTube videos with filters and pagination.

Parameter	Required	Description
`q`	Yes	Search query (min 2 characters)
`country`	No	2-letter country code (default: us)
`language`	No	Language code (default: en)
`page_token`	No	Previous response's continuation_token, to fetch the next page
`limit`	No	Max results (default 20, max 50)

Request

curl "https://getyoutubetranscript.com/api/v1/search?q=lofi+beats" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "query": "lofi beats",
    "video_results": [ { "title": "...", "videoId": "...", "channel": { "name": "..." } } ],
    "continuation_token": "c_bKt9xQ2mVf7LpR0aZ3sWyA"
  }
}

GET/resolve1 credit

Resolve a channel handle, URL, or username to its real channel ID. A syntactic input (already a channel ID or URL containing one) resolves instantly with no network call; a bare handle triggers one real lookup.

Parameter	Required	Description
`handle`	Yes	Channel ID, URL, or @handle

Request

curl "https://getyoutubetranscript.com/api/v1/resolve?handle=@mkbhd" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
    "title": "Marques Brownlee",
    "handle": "http://www.youtube.com/@mkbhd",
    "resolved_via": "lookup"
  }
}

GET/channel/latest1 credit

Channel details (title, handle, subscribers, video count, description, avatar) plus its 15 newest uploads. For the full upload history use /channel/videos.

Parameter	Required	Description
`channel`	Yes	Channel @handle, URL, or channel ID

Request

curl "https://getyoutubetranscript.com/api/v1/channel/latest?channel=@mkbhd" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "channel": { "id": "UCBJycsmduvYEL83R_U4JriQ", "title": "Marques Brownlee", "subscribers": 1160000, "avatar": "https://..." },
    "about": { "description": "...", "links": [] },
    "videos_sections": [ ... ]
  }
}

GET/channel/videos1 credit / page

Every video a channel has uploaded, newest first, paginated.

Parameter	Required	Description
`channel`	Yes	Channel @handle, URL, or channel ID
`continuation`	No	continuation_token from the previous response, to fetch the next page (use it instead of the other parameters). Expires after 24 hours.

Request

curl "https://getyoutubetranscript.com/api/v1/channel/videos?channel=@mkbhd" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "videos": [ { "position": 1, "id": "...", "title": "...", "views": "6.2M", "published_time": "1d ago", "length": "10:47" } ],
    "has_more": true,
    "continuation_token": "c_pqHR9v13sqaqxlcKhA4MnA"
  }
}

GET/channel/search1 credit / page

Search within one channel's videos, paginated.

Parameter	Required	Description
`channel`	Yes	Channel @handle, URL, or channel ID
`q`	Yes	Search query (min 2 characters)
`continuation`	No	continuation_token from the previous response, to fetch the next page (use it instead of the other parameters). Expires after 24 hours.

Request

curl "https://getyoutubetranscript.com/api/v1/channel/search?channel=@mkbhd&q=iphone" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "videos": [ { "position": 1, "id": "...", "title": "...", "published_time": "3w ago", "length": "17:14", "channel": { "name": "Marques Brownlee" } } ],
    "has_more": true,
    "continuation_token": "c_pnm10M6orzLgOTVWJk2oww"
  }
}

GET/playlist1 credit / page

Every video in a playlist, paginated. continuation_token is null on the last page.

Parameter	Required	Description
`list`	Yes	Playlist ID or URL
`continuation`	No	continuation_token from the previous response, to fetch the next page (use it instead of the other parameters). Expires after 24 hours.

Request

curl "https://getyoutubetranscript.com/api/v1/playlist?list=PLxxx" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "playlist_id": "PLxxx",
    "title": "...",
    "videos": [ { "position": 1, "id": "...", "title": "...", "channel": { "name": "..." } } ],
    "has_more": true,
    "continuation_token": "c_DfE9mQx2Ln8TbW4kJ1pZsA"
  }
}

GET/creditsFree

Check the remaining credit balance for this key before spending it - same data the MCP get_credits tool returns.

Parameter	Required	Description

Request

curl "https://getyoutubetranscript.com/api/v1/credits" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "success": true,
  "data": {
    "plan_credits_left": 87,
    "topup_credits_left": 0,
    "plan": "monthly",
    "rate_limit_per_minute": 200
  }
}

Errors

Errors return a JSON body with a stable code field to branch on, in addition to the HTTP status:

Status	Code	Meaning
400	`BAD_REQUEST`	Missing or invalid parameter
400	`CURSOR_EXPIRED`	Page cursor expired (after 24 hours) - start again from the first page
401	`MISSING_API_KEY / INVALID_API_KEY`	No key provided, or key is invalid/revoked
402	`PAYMENT_REQUIRED`	Out of credits - buy a top-up or upgrade
404	`VIDEO_UNAVAILABLE / TRANSCRIPT_NOT_FOUND`	Video or resource not found
429	`RATE_LIMITED`	Too many requests for your plan tier
503	`UPSTREAM_UNAVAILABLE`	Temporary upstream issue - safe to retry
504	`UPSTREAM_TIMEOUT`	Upstream took longer than 25 seconds - not charged, safe to retry

Using this API with an AI tool

Prefer letting Claude (or another AI coding tool) call this API for you instead of hand-writing requests? Download the YouTube Transcript skill - a ready-made Claude Skill that teaches it how to fetch transcripts, search, and more.

Use it in Zapier

No code needed: our Zapier app gets a transcript, searches YouTube or lists a channel's videos in any Zap. Connect it with the same API key; each action costs the same credits as the API call.

API Documentation

Authentication

Base URL

Credits & plans

Endpoints

Errors

Using this API with an AI tool

Use it in Zapier

Tools

Social media

Formats

AI agents

SDKs & automation