GitHubStart fetching
Reference

Batch Transcript API

One POST fetches a batch of transcripts concurrently, mixing YouTube, TikTok and Instagram URLs and bare YouTube ids in the same list. Each entry comes back with its own outcome: the transcript, a processing job for a video being transcribed from audio, or an error that costs nothing. The batch size follows the plan, and the rows a search, channel or playlist listing returns can be sent here unchanged.

1 credit per delivered caption transcript, failures freeView pricing

Entries with no caption track come back as processing, cost nothing on this call and are charged on delivery at the audio rate, 1 credit per started 5 minutes of audio. Failed entries are free.

Across platforms

  • Mix platforms freely: any URL the transcript endpoint accepts is accepted here.
  • Only delivered caption transcripts are billed on this call; captionless entries return processing with a job_id and are billed on delivery at the audio rate.
  • Re-send the same batch once the jobs have finished and the finished transcripts are returned inline from the cache.
POST/api/v2/transcripts/batchidempotent

Fetch up to 500 transcripts in one call (plan-dependent)

Fetch a batch of transcripts concurrently. Batch size follows your plan: up to 50 entries on the free tier, Basic and Pro, and up to 500 on Mega and Scale (a request over your plan's cap fails whole with a clear error before anything is fetched or charged). Accepts the same inputs as /transcripts/video - YouTube, TikTok and Instagram URLs as well as bare YouTube IDs. Charges 1 credit per successfully fetched caption transcript; failed videos are free. Entries with no caption track are transcribed from audio by default: those come back with outcome "processing" and a job_id, cost nothing on this call, and are charged on delivery at the audio rate. Re-send the same batch once they have finished and the text is returned normally - polling is optional. Send mode: "captions" to keep the old behaviour and have captionless entries fail as no_transcript instead.

Body parameters

video_idsstring[] (1–500, plan-dependent)required
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).
Example
mode"auto" | "captions"optional
Where each entry's text may come from. "auto" (the default) reads captions and transcribes the audio when there are none. "captions" reads an existing caption track only, so a captionless video fails as no_transcript - the behaviour batch had before audio fallback existed. Note "audio" is not accepted here: skipping captions for 50 videos at once is a job queue, not a batch fetch.
Example

Request example

curl https://transcriptfetch.com/api/v2/transcripts/batch \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_ids":["dQw4w9WgXcQ","https://www.tiktok.com/@user/video/7137723462233555205"],"mode":"auto"}'

Responses

SuccessExample response envelope
{
  "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": "audio"
          }
        }
      }
    ]
  },
  "usage": {
    "credits_spent": 1,
    "balance": 97
  }
}
Full endpoint reference

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 is transcribed from audio: 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 audio transcriptions 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.