V2 is the streamlined, user-owned transcript model. It prioritizes fast cache hits, consistent responses, and no surprise translations unless you request a language.
https://www.youtubetranscript.dev/api/v2Paste a YouTube link or video ID and get the transcript back, usually in seconds.
/transcribeSend up to 3,000 videos in one request and get notified when they're done.
/batchTurn a playlist or channel into its list of videos, ready to transcribe.
/playlists/resolveUpload a file and transcribe it with speech-to-text.
/uploadsList, fetch, translate or delete the transcripts you own.
/transcriptsCheck on speech-to-text jobs, or get a webhook when they finish.
/jobs/{job_id}New: one mode parameter for every transcript source
Choose auto, captions_only, human_captions_only, speech_to_text_only instead of combining source and allow_asr. Existing requests keep working exactly as before. See how it works
Download the YAML to import into Postman, Insomnia, generate clients, or paste into ChatGPT / Claude.
The fastest path for one video at a time. Caption-based transcripts return within a few seconds; ASR runs asynchronously and is polled via /api/v2/jobs/{job_id}.
Transcribe a single YouTube video. Returns immediately for caption-based videos. With mode=auto it falls back to ASR (async) when captions are unavailable: you get status processing and a job_id to poll at /api/v2/jobs/{job_id}, or the result is POSTed to webhook_url if you set one. Responses include the mode the request ran with.
/api/v2/transcribevideostringrequiredYouTube URL or 11-character video ID. Required unless upload_id is set.
upload_idstringTranscribe an uploaded media file instead of a YouTube video (see /uploads). Forces the ASR path (mode must be omitted or speech_to_text_only); webhook_url required. The upload id is returned as video_id in results.
modeauto | captions_only | human_captions_only | speech_to_text_onlyWhere the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). When omitted, your account default from the API Dashboard applies: auto for accounts created from October 2026, captions_only for older accounts unless changed. ASR modes work without webhook_url: poll the returned job_id.
languageISO 639-1Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.
sourceauto | manual | asrLegacy, still supported: use mode instead. Default: auto. asr transcribes the audio (async, requires webhook_url).
allow_asrbooleanLegacy, still supported: use mode=auto instead. Falls back to ASR if captions fail.
formatobject{ timestamp, paragraphs, words }: include extra structure in the transcript.
webhook_urluriWhen set, ASR results are POSTed to your URL. Optional with mode (poll the job_id instead); required for legacy source=asr. Ignored by captions_only and human_captions_only, which never use ASR.
asr_optionsobjectRich ASR config: language (+ codeSwitching, medicalMode, keyTerms), translateTo, speaker diarization (speakerLabels, speakerId + type/known values, multichannel, exact or min/max expected speakers), speech understanding (topics, summary, moderation, PII, profanity, sentiment), and formatting (punctuation, text formatting, filler words, custom date/phone/email patterns). Billable add-ons increase cost: preview with /transcribe/estimate. See the AsrOptions schema in the OpenAPI spec.
curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video": "dQw4w9WgXcQ",
"mode": "auto",
"language": "en",
"format": { "timestamp": true, "paragraphs": true }
}'{
"request_id": "req_abc123",
"status": "completed",
"data": {
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"transcript": {
"text": "Welcome to this tutorial...",
"language": "en",
"source": "auto",
"segments": [
{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
]
}
},
"credits_used": 1,
"mode": "auto"
}Dry-run credit estimate. Returns the ASR base cost plus any add-on surcharge for the requested asr_options without creating a job or charging credits.
/api/v2/transcribe/estimatevideostringrequiredYouTube URL or 11-character video ID.
modeauto | captions_only | human_captions_only | speech_to_text_onlySame values as /transcribe. Use speech_to_text_only (or auto) to preview the ASR cost.
sourceauto | manual | asrLegacy, still supported: use mode instead. Defaults to asr for cost preview.
asr_optionsobjectSame shape as /transcribe. Add-on charges are prorated by duration.
curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe/estimate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video": "dQw4w9WgXcQ",
"mode": "speech_to_text_only",
"asr_options": {
"speakerLabels": true,
"summarization": true,
"translateTo": "es"
}
}'{
"request_id": "req_abc123",
"video_id": "dQw4w9WgXcQ",
"source": "asr",
"mode": "speech_to_text_only",
"duration_seconds": 213,
"duration_minutes": 4,
"max_duration_minutes": 480,
"exceeds_max_duration": false,
"base_credits": 3,
"addon_credits": 2,
"estimated_credits": 5
}Poll a single transcription job. Use this for ASR jobs returned from /transcribe. Returns 202 while running and 200 when complete. Completed ASR jobs include asr_intelligence (summary, topics, sentiment, etc.) when those options were enabled.
/api/v2/jobs/{job_id}job_idpathrequiredIdentifier returned in the original transcribe response.
include_segmentsbooleanInclude segment-level timestamps in the transcript payload.
include_paragraphsbooleanInclude paragraph groupings.
include_wordsbooleanInclude word-level timestamps (ASR only).
curl -X GET https://www.youtubetranscript.dev/api/v2/jobs/JOB_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "req_abc123",
"status": "completed",
"data": {
"video_id": "dQw4w9WgXcQ",
"transcript": {
"text": "Welcome to this tutorial...",
"language": "en",
"source": "asr",
"segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }]
}
},
"credits_used": 6
}Transcribe your own audio or video files through the ASR pipeline. Three steps: register the upload, PUT the bytes to the signed URL, finalize: then call /transcribe with upload_id. Results arrive via your webhook and are polled like any ASR job.
Register an audio/video file upload and get a signed URL. PUT the raw file bytes to signed_url (with the file's Content-Type), finalize via /uploads/{upload_id}/complete, then transcribe with upload_id on /transcribe. Max 2GB and 8 hours per file.
/api/v2/uploadsfilenamestringrequiredOriginal filename. The extension is preserved for content sniffing.
mime_typestringrequiredMust start with audio/ or video/ (e.g. audio/mpeg, video/mp4).
size_bytesintegerrequiredFile size in bytes. Max 2147483648 (2GB).
duration_secintegerrequiredMedia duration in seconds. Max 28800 (8 hours). Used for the ASR credit estimate.
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filename": "interview.mp3",
"mime_type": "audio/mpeg",
"size_bytes": 48211234,
"duration_sec": 1820
}'
# Then PUT the raw file bytes to the returned signed_url:
curl -X PUT "SIGNED_URL_FROM_RESPONSE" \
-H "Content-Type: audio/mpeg" \
--data-binary @interview.mp3
# Then finalize:
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/UPLOAD_ID/complete \
-H "Authorization: Bearer YOUR_API_KEY"{
"upload_id": "up_a1B2c3D4",
"bucket": "asr-media",
"path": "user-uuid/up_a1B2c3D4/interview.mp3",
"token": "eyJhbGciOiJIUzI1NiJ9...",
"signed_url": "https://api.youtubetranscript.dev/storage/v1/object/upload/sign/asr-media/...?token=..."
}Finalize an upload after the PUT to signed_url succeeds. Verifies the file exists in storage and marks it ready. The upload can then be transcribed by passing upload_id to /transcribe (source="asr", webhook_url required).
/api/v2/uploads/{upload_id}/completeupload_idpathrequiredUpload id returned by POST /uploads.
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/up_a1B2c3D4/complete \
-H "Authorization: Bearer YOUR_API_KEY"{
"upload_id": "up_a1B2c3D4",
"status": "uploaded",
"filename": "interview.mp3",
"duration_sec": 1820
}Transcribe many videos in a single request, then poll or receive results via webhook.
Submit up to 3,000 videos in one request. Returns within 2 seconds; poll the returned poll_url or wait for the webhook.
/api/v2/batchvideo_idsstring[]requiredUp to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.
languageISO 639-1Preferred language for every video.
modeauto | captions_only | human_captions_only | speech_to_text_onlyWhere the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). For batch, auto and speech_to_text_only require webhook_url. When omitted, your API Dashboard default applies (an ASR default only when webhook_url is set).
sourceauto | manual | asrLegacy, still supported: use mode instead. Default: auto. source=asr requires webhook_url.
allow_asrbooleanLegacy, still supported: use mode=auto instead. webhook_url is required.
formatobject{ timestamp, paragraphs, words }: applied to every result.
webhook_urluriDelivers the completed batch payload. Required for mode=auto or speech_to_text_only (legacy: allow_asr=true or source=asr).
asr_optionsobjectRich ASR config applied to every video transcribed via ASR (same shape as /transcribe). Billable add-ons apply per video.
curl -X POST https://www.youtubetranscript.dev/api/v2/batch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
"mode": "auto",
"webhook_url": "https://your-domain.com/webhook",
"format": { "timestamp": true }
}'{
"batch_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"results": [],
"summary": { "total": 2, "succeeded": 0, "failed": 0, "processing": 2 },
"poll_url": "https://www.youtubetranscript.dev/api/v2/batch/550e8400-e29b-41d4-a716-446655440000",
"created_at": "2026-05-15T10:00:00Z"
}Check the status of a batch. Returns 202 while processing and 200 when results are ready. Stop polling once status is "completed", "partial", or "failed": finished batches never change, and re-fetching one more than 60 times in 24h returns 429 with a Retry-After header.
/api/v2/batch/{batch_id}batch_idpathrequiredBatch identifier returned from POST /batch.
curl -X GET https://www.youtubetranscript.dev/api/v2/batch/BATCH_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"batch_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"summary": { "total": 2, "succeeded": 2, "failed": 0, "processing": 0 },
"results": [
{ "request_id": "req_1", "status": "completed", "data": { "video_id": "dQw4w9WgXcQ" } },
{ "request_id": "req_2", "status": "completed", "data": { "video_id": "jNQXAC9IVRw" } }
],
"credits_used": 2,
"webhook_delivered": true,
"completed_at": "2026-05-15T10:04:00Z"
}List, fetch, translate, and delete your stored transcripts, and list async jobs. All endpoints accept the same API-key auth.
List your transcription jobs, newest first. Filter by status and paginate. Use the returned job_id with GET /api/v2/jobs/{job_id} to fetch a transcript.
/api/v2/jobspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
statusquerycompleted | processing | failed | requires_asr_confirmation.
curl "https://www.youtubetranscript.dev/api/v2/jobs?status=processing&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"{
"jobs": [
{
"job_id": "9c2...",
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"language": "en",
"source": "asr",
"status": "processing",
"error": null,
"credits_used": 0,
"created_at": "2026-07-06T12:00:00Z",
"started_at": "2026-07-06T12:00:01Z",
"completed_at": null
}
],
"count": 1,
"pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasMore": false }
}List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.
/api/v2/transcriptspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
searchqueryMatch video id, title, or transcript text.
statusqueryFilter by status; omit for succeeded.
languagequeryFilter by language code.
date_fromqueryISO date-time lower bound.
date_toqueryISO date-time upper bound.
include_segmentsqueryInclude segments in each item.
curl "https://www.youtubetranscript.dev/api/v2/transcripts?page=1&limit=50&status=succeeded" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{
"id": "b1f...",
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"language": "en",
"source_kind": "auto",
"status": "succeeded",
"created_at": "2026-07-06T12:00:00Z",
"word_count": 1234,
"segment_count": 88,
"credits_used": 1
}
],
"count": 1,
"pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasMore": false }
}Fetch the best owned transcript for a video, including asr_intelligence (summary, topics, sentiment, etc.), plus summary and mind_map when generated.
/api/v2/transcripts/{video_id}video_idpathrequiredYouTube 11-character video ID.
idquerySpecific transcript/job id.
languagequeryPreferred language version.
sourcequeryauto | manual | asr.
include_timestampsqueryInclude segments (default true).
curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ?language=en" \
-H "Authorization: Bearer YOUR_API_KEY"{
"id": "b1f...",
"video_id": "dQw4w9WgXcQ",
"language": "en",
"text": "Welcome to this tutorial...",
"segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }],
"has_timestamps": true,
"source_kind": "asr",
"video_title": "Example video",
"summary": null,
"mind_map": null,
"asr_intelligence": {
"summary": "A short overview of the video...",
"topics": [{ "text": "Technology", "relevance": 0.92 }],
"sentiment": [{ "text": "Great tutorial", "sentiment": "POSITIVE" }]
}
}Translate an owned transcript into a target language using YouTube captions or the AI provider. Returns free if you already own the translation.
/api/v2/transcripts/{video_id}/translatevideo_idpathrequiredYouTube 11-character video ID.
target_languageISO 639-1requiredLanguage to translate into.
source_languageISO 639-1Source transcript language to translate from.
providerai | youtubeTranslation provider.
allow_ai_fallbackbooleanFall back to AI when YouTube has no translation.
curl -X POST "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/translate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "target_language": "es", "provider": "ai" }'{
"success": true,
"message": "Translation completed",
"language": "es",
"credits_used": 4,
"provider_used": "ai"
}List the languages you already own for a video plus the YouTube translation targets available for it.
/api/v2/transcripts/{video_id}/languagesvideo_idpathrequiredYouTube 11-character video ID.
include_youtube_defaultqueryInclude YouTube translation targets (default true).
curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/languages" \
-H "Authorization: Bearer YOUR_API_KEY"{
"video_id": "dQw4w9WgXcQ",
"languages": ["en", "es"],
"youtube_translation_languages": ["fr", "de", "ja"]
}Delete owned transcript(s) for a video. Optional language/source query params narrow the deletion; otherwise every language/source is removed. Also deletes bulk by id via POST /api/v2/transcripts/bulk-delete.
/api/v2/transcripts/{video_id}video_idpathrequiredYouTube 11-character video ID.
languagequeryOnly delete this language.
sourcequeryOnly delete this source (auto | manual | asr).
curl -X DELETE "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ" \
-H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"deleted": 2,
"message": "Successfully deleted 2 transcripts"
}Resolve a playlist into video IDs, transcribe them with /api/v2/batch, then inspect the playlist batch and history.
Resolve a YouTube playlist by URL or ID into its video list (metadata only). Pair the returned video_id values with /api/v2/batch to transcribe them.
/api/v2/playlists/resolvePaid plansplaylist_urlstringPlaylist URL. One of playlist_url or playlist_id is required.
playlist_idstringPlaylist ID (the list= value).
limitintegerMax videos returned (1-100).
curl -X POST https://www.youtubetranscript.dev/api/v2/playlists/resolve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "playlist_url": "https://www.youtube.com/playlist?list=PLxxxx", "limit": 100 }'{
"playlist_id": "PLxxxx",
"title": "My playlist",
"total": 42,
"truncated": false,
"items": [
{ "video_id": "dQw4w9WgXcQ", "title": "Example video" }
]
}Fetch a playlist batch and per-video transcription job status. For overall batch progress, poll GET /api/v2/batch/{batch_id}.
/api/v2/playlists/{playlist_id}playlist_idpathrequiredBatch ID returned from /playlists/resolve.
curl "https://www.youtubetranscript.dev/api/v2/playlists/{playlist_batch_id}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"playlist": { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist" },
"videos": [
{ "video_id": "dQw4w9WgXcQ", "video_title": "Example video", "status": "succeeded" }
]
}List recent playlist batches for the authenticated user.
/api/v2/playlists/historycurl "https://www.youtubetranscript.dev/api/v2/playlists/history" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{ "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist", "total_videos": 42 }
],
"count": 1
}Channel transcription flow:1. POST /api/v2/channels/resolve: fetch the channel uploads (video metadata only).2. POST /api/v2/batch: send the returned video_id values to start transcription. Use a webhook_url to receive results when done.3. GET /api/v2/batch/{batch_id}: poll the batch for overall progress and aggregated results.4. GET /api/v2/channels/{channel_id}: fetch a channel batch with per-video job status; /channels/history lists past channel batches.
Fetch the uploads of a YouTube channel by URL, channel ID, or @handle. Returns video metadata only: pair the returned video_id values with /api/v2/batch to transcribe them.
/api/v2/channels/resolvePaid planschannel_urlstringrequiredYouTube channel URL, channel ID, or @handle. One of channel_url, channel_id, or handle must be provided. Handles are the public ID without the @ (for https://www.youtube.com/@jawed, the ID is jawed).
limitintegerMaximum uploads returned. Defaults to the plan maximum.
Per-request cap: Basic 500 videos · Pro 1,500 videos · Business 3,000 videos. Monthly job cap: Basic 3 · Pro 8 · Business unlimited.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
curl -X POST https://www.youtubetranscript.dev/api/v2/channels/resolve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"handle": "@youtube",
"limit": 50
}'{
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"subscriber_count": 42000000,
"video_count": 1200,
"total": 1,
"truncated": false,
"items": [
{
"video_id": "dQw4w9WgXcQ",
"title": "Latest upload",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"published_at": "2026-05-01T12:00:00Z",
"duration_seconds": 420
}
]
}Fetch a channel batch and the per-video transcription job status. For overall batch status (counts + progress), poll GET /api/v2/batch/{batch_id} instead: use this endpoint when you also need each video's individual job state.
/api/v2/channels/{channel_id}channel_idpathrequiredBatch ID returned from /channels/resolve.
curl -X GET https://www.youtubetranscript.dev/api/v2/channels/CHANNEL_BATCH_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"channel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"total_videos": 2,
"completed_count": 1,
"failed_count": 0,
"status": "processing",
"created_at": "2026-05-15T10:00:00Z"
},
"videos": [
{
"id": "job_123",
"video_id": "dQw4w9WgXcQ",
"video_title": "Latest upload",
"status": "succeeded",
"created_at": "2026-05-15T10:00:00Z",
"finished_at": "2026-05-15T10:00:10Z"
}
]
}List recent channel batches for the authenticated user.
/api/v2/channels/historylimitqueryMax items (default 50, max 100).
curl -X GET "https://www.youtubetranscript.dev/api/v2/channels/history?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"total_videos": 25,
"completed_count": 25,
"failed_count": 0,
"status": "completed",
"created_at": "2026-05-15T10:00:00Z",
"completed_at": "2026-05-15T10:12:00Z"
}
],
"count": 1
}Search, then transcribe:1. GET /api/v2/search/videos (/shorts, /channels, /playlists): find content by keyword. 1 credit per request.2. Send a video's url to POST /api/v2/transcribe, or a channel or playlist url to /api/v2/channels/resolve or /api/v2/playlists/resolve.3. Pass next_page_token as page_token to get more results (1 credit per page).
Search YouTube videos by keyword. Live streams are included with type "live". Pass a result's url to /api/v2/transcribe to get its transcript. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/videosqqueryrequiredSearch text, up to 200 characters.
durationqueryVideo length: under_3_min, 3_to_20_min or over_20_min.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
curl "https://www.youtubetranscript.dev/api/v2/search/videos?q=python%20tutorial&duration=over_20_min" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "6f1c2a9e-4b7d-4f2a-9c1e-2d3b4a5c6d7e",
"type": "videos",
"query": "python tutorial",
"results": [
{
"type": "video",
"video_id": "kqtD5dpn9C8",
"url": "https://www.youtube.com/watch?v=kqtD5dpn9C8",
"title": "Python for Beginners - Learn Coding with Python in 1 Hour",
"thumbnail": "https://i.ytimg.com/vi/kqtD5dpn9C8/hq720.jpg",
"channel": {
"channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
"title": "Programming with Mosh",
"handle": "programmingwithmosh",
"url": "https://www.youtube.com/@programmingwithmosh",
"thumbnail": "https://yt3.ggpht.com/..."
},
"view_count": 25574982,
"view_count_text": "25,574,982 views",
"published_at": null,
"published_text": "6 years ago",
"duration_seconds": 3606,
"duration_text": "1:00:06",
"badges": []
}
],
"next_page_token": "cDA6RWdJUUFV...",
"credits_used": 1,
"credits_remaining": 4602
}Search YouTube Shorts by keyword. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/shortsqqueryrequiredSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
curl "https://www.youtubetranscript.dev/api/v2/search/shorts?q=python%20tips" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"type": "shorts",
"query": "python tips",
"results": [
{
"type": "short",
"video_id": "gbYLsUngzLc",
"url": "https://www.youtube.com/watch?v=gbYLsUngzLc",
"title": "Top 10 Most Important Python Functions You Must Know!",
"thumbnail": "https://i.ytimg.com/vi/gbYLsUngzLc/oar2.jpg",
"channel": null,
"view_count": 1200000,
"view_count_text": "1.2M views",
"published_at": null,
"published_text": null,
"duration_seconds": null,
"duration_text": null,
"badges": []
}
],
"next_page_token": "cDA6RWdJUUNR...",
"credits_used": 1,
"credits_remaining": 4601
}Search YouTube channels by keyword. Pass a result's url to /api/v2/channels/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/channelsqqueryrequiredSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
curl "https://www.youtubetranscript.dev/api/v2/search/channels?q=python" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"type": "channels",
"query": "python",
"results": [
{
"type": "channel",
"channel_id": "UCKQdc0-Targ4nDIAUrlfKiA",
"url": "https://www.youtube.com/@PythonSimplified",
"title": "Python Simplified",
"handle": "PythonSimplified",
"description": "Hi everyone! My name is Mariya and I'm a software developer...",
"thumbnail": "https://yt3.googleusercontent.com/...",
"subscriber_count": 286000,
"subscriber_count_text": "286K",
"badges": ["Verified"]
}
],
"next_page_token": "cDA6RWdJUUFn...",
"credits_used": 1,
"credits_remaining": 4600
}Search YouTube playlists by keyword. Pass a result's url to /api/v2/playlists/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/playlistsqqueryrequiredSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
curl "https://www.youtubetranscript.dev/api/v2/search/playlists?q=python%20course" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"type": "playlists",
"query": "python course",
"results": [
{
"type": "playlist",
"playlist_id": "PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
"url": "https://www.youtube.com/playlist?list=PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
"title": "Python Tutorial | Complete Python Course (Beginner to Advanced)",
"thumbnail": "https://i.ytimg.com/vi/YZkyL-f-YXY/hq720.jpg",
"video_count": 54,
"first_video_id": "YZkyL-f-YXY",
"channel": {
"channel_id": "UC59K-uG2A5ogwIrHw4bmlEg",
"title": "Telusko",
"handle": "Telusko",
"url": "https://www.youtube.com/@Telusko",
"thumbnail": null
}
}
],
"next_page_token": "cDA6RWdJUUF3...",
"credits_used": 1,
"credits_remaining": 4599
}Official SDKs, an MCP server for Claude and Cursor, a custom GPT, and ready-made templates for Make and n8n.
Add the YouTube Transcript MCP server to Claude Desktop, Cursor, or any MCP-compatible client. Adds tools to transcribe videos, fetch existing transcripts, and check usage.
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"First-class TypeScript types, retries, pagination helpers, and webhook signature verification.
npm install youtube-transcript-apiSync + async clients, type stubs, and helpers for batch and webhook flows.
pip install youtubetranscriptdevapiDrop our custom GPT into ChatGPT to summarize, quote, translate, or query any YouTube video using natural language. Backed by /api/v2/gpt/* under the hood.
Import the template (or copy the snippet) to add transcription to existing automations: Notion, Sheets, Slack, Airtable, Zapier-style flows.
Module: HTTP > Make a request
- URL: https://www.youtubetranscript.dev/api/v2/transcribe
- Method: POST
- Headers:
Authorization: Bearer {{connection.api_key}}
Content-Type: application/json
- Body type: Raw / JSON
- Request content:
{
"video": "{{1.video_url}}",
"format": { "timestamp": true }
}{
"name": "Transcribe Video",
"type": "n8n-nodes-base.httpRequest",
"parameters": {
"method": "POST",
"url": "https://www.youtubetranscript.dev/api/v2/transcribe",
"authentication": "genericCredentialType",
"genericAuthType": "httpHeaderAuth",
"sendBody": true,
"specifyBody": "json",
"jsonBody": "={ \"video\": $json.video_url }"
}
}Import the OpenAPI spec into Postman, Insomnia, or any tool that speaks OpenAPI 3.
Errors return a JSON body with code and message. HTTP status reflects the category.
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Invalid JSON or missing required fields |
| 401 | invalid_api_key | Missing or invalid API key |
| 402 | payment_required | Insufficient credits |
| 404 | no_captions | No captions available and ASR not used |
| 429 | rate_limit_exceeded | Too many requests, check Retry-After |
| 500 | internal_error | Server error, retry with backoff |
Per-plan caps for sustained requests and batch sizes. Bursting above the limit returns 429 with a Retry-After header.
| Plan | Requests | Batch size |
|---|---|---|
| Free | 1 req/s | 10 videos |
| Basic | 25 req/s | 500 videos |
| Pro | 50 req/s | 1,500 videos |
| Business | 100 req/s | 3,000 videos |
Need help shipping? Reach out: we usually reply within a few hours.