API reference

Response format

Every successful response shares the same envelope: ok, a request_id (also returned as the X-Request-Id header), a data object whose kind tells you what it holds, and a usage block.

Single transcript

The /video endpoint returns kind: "transcript" with the full text and a timestamped segments array. Each segment's start and duration are in seconds, everything you need to render timestamps or export SRT/VTT.

JSON

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "transcript",
    "video_id": "dQw4w9WgXcQ",
    "platform": "youtube",
    "title": "Example video",
    "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
    "text": "We're no strangers to love …",
    "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)

The /channel, /playlist, and /search endpoints return kind: "video_list", a videos array of metadata plus a next_cursor for pagination. Fetch the transcripts separately via the batch endpoint.

JSON

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "video_list",
    "source": "search",
    "videos": [
      {
        "videoId": "dQw4w9WgXcQ",
        "title": "Example video",
        "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
        "duration": 212,
        "channel": "Example Channel"
      }
    ],
    "next_cursor": "eyJvIjoxMH0"
  },
  "usage": {
    "credits_spent": 1,
    "balance": 98,
    "bytes": 0
  }
}

Batch

The batch endpoint returns kind: "transcript_batch" with one entry per requested video in data.results.

JSON

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "transcript_batch",
    "results": [
      {
        "video_id": "dQw4w9WgXcQ",
        "outcome": "ok",
        "title": "Example video",
        "text": "Full transcript text …",
        "segments": [
          {
            "start": 0,
            "duration": 3.5,
            "text": "Full transcript …"
          }
        ],
        "cached": true,
        "bytes": 14233
      },
      {
        "video_id": "9bZkp7q19f0",
        "outcome": "no_transcript",
        "title": null,
        "text": null,
        "segments": null,
        "cached": false,
        "bytes": 0
      }
    ]
  },
  "usage": {
    "credits_spent": 1,
    "balance": 97
  }
}

Field reference

data.kind, transcript, video_list, or transcript_batch.
segments, array of { start, duration, text } cues (seconds), or null when no transcript is available.
next_cursor, pass back as cursor for the next page of a list, or null when exhausted.
outcome (batch results), ok, no_transcript, blocked, or error.
usage.credits_spent, credits charged for this request (0 on failures).
usage.balance, your remaining credit balance (null for unlimited accounts).

Next →Error codes & outcomes