Body parameters
- type
string[] (1–500, plan-dependent)- required
true- description
- Video URLs or bare YouTube IDs, from any supported platform.
- Up to your plan's batch cap: 50 on free/Basic/Pro, 500 on Mega/Scale.
- Also accepted as the legacy key
videoIds(send one or the other, not both).
- type
string- required
false- values
autocaptions- description
- Where each entry's text may come from.
"auto"(the default) readscaptionsand uses AI Fallback Transcription when there are none, charged on delivery at 1 credit per started 5 minutes of audio."captions"reads an existing caption track only, so a captionless entry fails (error codeno_captions) and nothing is charged for audio."audio"is not accepted here: skippingcaptionsfor 50 videos at once is a job queue, not a batch fetch.
- type
boolean- required
false- default
false- description
- Beta.
trueaddsmarkdownto the transcript: a title line, a line with the channel, length and link, then paragraphs that each open with their time (linked to that moment on YouTube).- Works with timestamps on or off.
- Free.
- Absent by default, so leaving it out changes nothing.
- type
boolean | { max_tokens, overlap_tokens }- required
false- description
- Beta.
- Adds
chunks: the transcript split into pieces sized for an embedding model or vector store. - Each piece has index, text, start and end (seconds,
nullwhen the transcript has no timings), url (opens the video at start on YouTube; the item's link on other platforms) and tokens. - Pieces break between caption lines, never mid-word, and overlap the previous piece slightly.
trueusesmax_tokens500 andoverlap_tokens50; an object sets either:max_tokens100 to 2000,overlap_tokens0 to 200 and smaller thanmax_tokens.- Tokens are counted with OpenAI's o200k_base encoding.
- Free.
- Absent by default.
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "transcript_batch",
"results": [
{
"video_id": "dQw4w9WgXcQ",
"outcome": "ok",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"title": "Example video",
"channel": "Example Channel",
"duration": 212,
"language": "en",
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
"source": "captions",
"text": "Full transcript text …",
"segments": [
{
"start": 0,
"duration": 3.5,
"text": "Full transcript …"
}
],
"bytes": 14233
},
{
"video_id": "9bZkp7q19f0",
"outcome": "processing",
"job_id": "asr_…",
"poll_url": "/api/v2/transcripts/jobs/asr_…"
},
{
"video_id": "jNQXAC9IVRw",
"outcome": "error",
"error": {
"code": "no_captions",
"number": 4103,
"message": "No caption track (manual or auto-generated) is available.",
"docs": "https://transcriptfetch.com/docs/errors/no_captions",
"retry_with": {
"mode": "auto"
}
}
}
]
},
"usage": {
"credits_spent": 1,
"balance": 97
}
}Frequently asked questions
How many videos can one batch hold?
It depends on the plan, as stated on the endpoint: a smaller cap on the free tier, Basic and Pro, and a larger one on Mega and Scale. A batch over your cap fails whole, before anything is fetched or charged.
What happens to videos without captions in a batch?
With the default mode, auto, each one goes to AI Fallback Transcription: its entry comes back as processing with a job_id, costs nothing on this call, and is billed on delivery. Send mode captions to have such entries fail as no_captions instead.
Do failed entries cost credits?
No. Only successfully delivered caption transcripts are billed on the call, and AI Fallback Transcription only on delivery. An entry that is private, removed or blocked reports an error and costs nothing.
How do I collect the transcripts that were still processing?
Re-send the same batch after the jobs have had time to finish. Finished entries return their text from the cache and are not charged twice; polling each job_id is optional.