Response format

Single transcript

The /video endpoint returns kind: "transcript" with either segments or text, never both. The other key is absent, not null, so check for presence, not truthiness.

Every transcript carries the same metadata, whichever platform or path served it. Every key is always present; null means unknown, never omitted. A cache hit, an inline audio result, a job poll and a webhook delivery all carry exactly these keys.

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "transcript",
    "video_id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "title": "Example video",
    "channel": "Example Channel",
    "duration": 212,
    "language": "en",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
    "source": "captions",
    "segments": [
      {
        "start": 0,
        "duration": 3.5,
        "text": "We're no strangers to love"
      }
    ]
  },
  "usage": {
    "credits_spent": 1,
    "balance": 99,
    "bytes": 14233
  }
}

Video list (channel / playlist / search)

/channel, /playlist and /search return kind: "video_list": a videos array of metadata and a next_cursor for the next page. Fetch the transcripts separately with the batch endpoint.

A list can also carry a notice saying why a page is empty or may be incomplete, such as "This channel has no Live tab."

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "video_list",
    "source": "search",
    "platform": "tiktok",
    "videos": [
      {
        "videoId": "7398765432101234567",
        "url": "https://www.tiktok.com/@examplecreator/video/7398765432101234567",
        "title": "the post caption",
        "duration": 58,
        "channel": "@examplecreator",
        "publishedAt": "2026-08-30T14:02:00Z",
        "stats": {
          "plays": 1240000
        }
      }
    ],
    "next_cursor": "eyJvIjoxMH0"
  },
  "usage": {
    "credits_spent": 1,
    "balance": 98,
    "bytes": 0
  }
}

Playlist and channel lists

Some YouTube listings return playlists or channels instead of videos. Both page with next_cursor like a video list, and every row's url is accepted as-is by the playlist or channel endpoint.

The channel and search references show a full example of each.

Batch

The batch endpoint returns kind: "transcript_batch", one entry per requested video in data.results. Entries carry both text and segments (batch does not accept timestamps), plus an outcome:

Send mode: "captions" to have captionless entries fail as error with code no_captions (and a retry_with naming the audio mode) instead.

{
  "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
  }
}

Markdown and chunks for AI (beta)

Two optional request fields on /video and /batch repackage the transcript for an AI pipeline. Both are free, both work on every platform, and both are absent unless you ask, so a request without them answers exactly as before.

• "markdown": true adds markdown: a title line, a line with the channel, length and link, then paragraphs that each open with their time. On YouTube each time links to that moment in the video. Use it when a model will quote or cite the transcript.
• "chunks": true adds chunks: the transcript split into pieces sized for an embedding model or vector store. Each piece is { index, text, start, end, url, tokens }, where url opens the video at start (on YouTube; on TikTok and Instagram it is the video's own link). Pieces break between caption lines, never mid-word, and each repeats the end of the previous one so a sentence on the boundary is never lost. start and end are null when a transcript has no timings.
• Size the pieces with "chunks": { "max_tokens": 500, "overlap_tokens": 50 } (those are the defaults): max_tokens from 100 to 2000, overlap_tokens from 0 to 200 and smaller than max_tokens. Tokens are counted with OpenAI's o200k_base encoding, close to what Claude and Gemini count.

curl -X POST https://transcriptfetch.com/api/v2/transcripts/video \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video": "aircAruvnKk", "timestamps": false, "chunks": {"max_tokens": 500, "overlap_tokens": 50}}'

"chunks": [
  {
    "index": 0,
    "text": "This is a 3. It's sloppily written and rendered at an extremely low resolution of 28x28 pixels, …",
    "start": 4.22,
    "end": 139.18,
    "url": "https://www.youtube.com/watch?v=aircAruvnKk&t=4s",
    "tokens": 494
  },
  {
    "index": 1,
    "text": "There are many many variants of neural networks, …",
    "start": 125.04,
    "end": 272.34,
    "url": "https://www.youtube.com/watch?v=aircAruvnKk&t=125s",
    "tokens": 494
  }
]

That 18-minute video makes 9 pieces with the defaults. On batch, every ok entry gains the same keys. A captionless video that goes to AI Fallback Transcription remembers the options: its job poll and its webhook answer with markdown and chunks too. v1 does not take these fields.

Search with transcripts (beta)

Add transcripts to a YouTube, TikTok or Instagram video search and every video row comes back with a transcript, so one call goes from a query to what the videos say:

curl -X POST https://transcriptfetch.com/api/v2/transcripts/search \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how neural networks learn", "captions": true, "limit": 10, "transcripts": {"timestamps": false, "chunks": true}}'

Each row's transcript has the same shape as a batch entry without video_id: an outcome (ok, processing or error), then text, segments, markdown and chunks as asked, or the error block. transcripts: true fetches caption transcripts with timestamps; the object takes mode, timestamps, markdown and chunks. The mode defaults to "captions" here, so a search never starts paid AI Fallback Transcription unless you send "mode": "auto" (captionless rows then come back processing with a job, as in a batch). limit can be at most 10 with transcripts, and type must be a video search.

It costs the page's credit plus 1 credit per caption transcript delivered; failed rows are free. An account that cannot cover the page and every row is refused with 402 before anything is fetched.

Field reference

• data.kind: transcript, video_list, playlist_list, channel_list, transcript_batch, transcript_job, or me; the monitor endpoints answer with monitor, monitor_list, monitor_event_list, monitor_check and monitor_deleted.
• text / segments: exactly one on single-transcript responses (chosen by timestamps); both on batch entries and completed job results. Segments are { start, duration, text } cues in seconds (speaker added when diarized).
• next_cursor: pass back as cursor for the next page of a list, null when exhausted.
• outcome (batch results): ok, processing, or error; failed entries carry error (the standard block), and processing entries (captionless videos in AI Fallback Transcription) carry job_id and poll_url.
• video_id, url, platform, title, channel, duration, language, thumbnail_url (transcripts): the metadata block above, on every transcript-bearing response including job polls, webhooks and batch entries. Always present; null when unknown.
• source (transcripts): "captions" or "audio".
• markdown, chunks (transcripts, beta): present only when the request asked for them; see above.
• usage.credits_spent: credits charged for this request. Failures are never charged and carry no usage block.
• usage.balance: remaining credit balance (null for unlimited accounts).
• usage.bytes: upstream bytes this request consumed (absent on batch, which reports per-entry bytes).