TranscriptFetchGitHubGet API access
Reference

Endpoint reference

Request and response shapes for every v2 endpoint. Open Try it to send a live call.

POST/api/v2/transcripts/videoidempotent

Fetch a transcript

Fetch timestamped text from a video or media file.

  • auto uses captions first, then AI transcription when needed.
  • Audio work may return 202; poll the returned URL or provide callback_url.
  • Caption results cost 1 credit; AI transcription is priced by duration.

Body parameters

videostringrequired
YouTube, TikTok, Instagram, or direct media URL; a YouTube ID also works.
mode"captions" | "audio" | "auto"optional
auto tries captions then AI; captions never transcribes; audio always transcribes.
timestampsbooleanoptional
true returns timestamped segments; false returns joined text.
callback_urlstring (https URL)optional
HTTPS URL that receives the completed audio transcript.
ai_fallbackbooleanoptional
Deprecated alias for mode; prefer mode in new integrations.

Request example

curl https://transcriptfetch.com/api/v2/transcripts/video \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video":"dQw4w9WgXcQ"}'

Responses

SuccessExample response envelope
{
  "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
  }
}
GET/api/v2/transcripts/jobs/{jobId}

Check a transcription job

Check an audio transcription started by a 202 response.

  • Status is processing, completed, or failed.
  • Polling uses no TranscriptFetch credits.

Request example

curl https://transcriptfetch.com/api/v2/transcripts/jobs/{jobId} \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY"

Responses

SuccessExample response envelope
{
  "ok": true,
  "request_id": "req_…",
  "status": "completed",
  "job_id": "asr_m3k1x9qz4vb2p7",
  "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": "audio",
    "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": 942,
    "bytes": 18244
  }
}
POST/api/v2/transcripts/batchidempotent

Fetch transcripts in batch

Fetch transcripts for up to 50 videos at once.

  • Only successful transcripts are billed.
  • Captionless items may return processing with a job ID.

Body parameters

video_idsstring[] (1–500, plan-dependent)required
One to 50 video URLs or YouTube IDs.
mode"auto" | "captions"optional
auto tries captions then AI; captions never transcribes; audio always transcribes.

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

Discovery

List channels and playlists or search for videos. Supported platforms are shown beside each endpoint.

POST/api/v2/transcripts/channelidempotent

List channel videos

List a YouTube channel's newest videos with cursor pagination.

  • since_video_id returns only newer uploads; an empty result is free.

Body parameters

channelstringrequired
YouTube @handle, channel URL, or UC… channel ID.
limitinteger (1–50)optional
Videos returned per page. Default 5; maximum 50.
cursorstringoptional
next_cursor from the previous response; omit on the first page.
since_video_idstringoptional
Return only uploads newer than this video ID.

Request example

curl https://transcriptfetch.com/api/v2/transcripts/channel \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"@lexfridman","limit":10}'

Responses

SuccessExample response envelope
{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "video_list",
    "source": "channel_videos",
    "platform": "youtube",
    "videos": [
      {
        "videoId": "dQw4w9WgXcQ",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "title": "Example video",
        "duration": 212,
        "channel": "Example Channel",
        "publishedAt": "2009-10-25T00:00:00Z",
        "stats": {
          "plays": 1600000000
        }
      }
    ],
    "next_cursor": "eyJvIjoxMH0"
  },
  "usage": {
    "credits_spent": 1,
    "balance": 98,
    "bytes": 0
  }
}
POST/api/v2/transcripts/playlistidempotent

List playlist videos

List the videos in a YouTube playlist.

Body parameters

playliststringrequired
YouTube playlist URL or playlist ID.
limitinteger (1–50)optional
Videos returned per page. Default 5; maximum 50.
cursorstringoptional
next_cursor from the previous response; omit on the first page.

Request example

curl https://transcriptfetch.com/api/v2/transcripts/playlist \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playlist":"PLrAXtmRdnEQy6nuLMt9H1aZIuhcGOcZQ4","limit":10}'

Responses

SuccessExample response envelope
{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "video_list",
    "source": "playlist",
    "platform": "youtube",
    "videos": [
      {
        "videoId": "dQw4w9WgXcQ",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "title": "Example video",
        "duration": 212,
        "channel": "Example Channel",
        "publishedAt": "2009-10-25T00:00:00Z",
        "stats": {
          "plays": 1600000000
        }
      }
    ],
    "next_cursor": "eyJvIjoxMH0"
  },
  "usage": {
    "credits_spent": 1,
    "balance": 98,
    "bytes": 0
  }
}
POST/api/v2/transcripts/searchidempotent

Search videos

Search YouTube and return a paginated video list.

Body parameters

querystringrequired
Keywords to search for on YouTube.
platformstring (enum)optional
Where to search: youtube (default), tiktok, or instagram. Every result's url is accepted by the transcript and batch endpoints as-is.
limitinteger (1–50)optional
Videos returned per page. Default 5; maximum 50.
cursorstringoptional
next_cursor from the previous response; omit on the first page.

Request example

curl https://transcriptfetch.com/api/v2/transcripts/search \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"how transformers work","platform":"tiktok","limit":10}'

Responses

SuccessExample response envelope
{
  "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
  }
}

Usage & service

Check credit usage, validate credentials, or monitor API availability.

GET/api/v2/me

Check credit usage

Validate an API key and read its current credit balance.

Request example

curl https://transcriptfetch.com/api/v2/me \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY"

Responses

SuccessExample response envelope
{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "me",
    "user_id": "user_…",
    "credits": 250
  },
  "usage": {
    "credits_spent": 0,
    "balance": 250,
    "bytes": 0
  }
}
GET/api/v2/healthno auth

Health check

Check whether the public API is serving requests.

Request example

curl https://transcriptfetch.com/api/v2/health

Responses

SuccessExample response envelope
{
  "status": "ok",
  "service": "transcriptfetch-api",
  "version": "2.0.0",
  "time": "2026-06-16T00:00:00.000Z"
}