How do I extract my first YouTube transcript with TubeTranscript?

By TubeTranscript · Content updated

View as Markdown

TubeTranscript parses a captioned YouTube video into a semantic JSON payload in seconds via the Tier-1 Fast Path. Use the web app (no account, 10 transcripts per 24 hours; 24 with a free account), the REST API POST /api/v1/extract, or the MCP servers /api/mcp and /api/mcp/tools; the API and MCP require a Pro plan API key.

If you plan to call it from code, the REST API page shows a first request in curl, Python and JavaScript.

Surface Account Limit Best for
Web app (https://tubetranscript.io) None required 10 transcripts / 24 h One-off transcripts
REST API (POST /api/v1/extract) Pro API key 1,000 requests / 24 h Scripts, n8n, Make
MCP servers (/api/mcp, /api/mcp/tools) Pro API key 1,000 tool calls / 24 h Claude Code, Cursor, Windsurf

How do I extract a transcript in the web app?

Open https://tubetranscript.io, paste a YouTube link into the "Drop a YouTube link." field and submit. Accepted links include watch, youtu.be, shorts, embed and live URLs. Guests get 10 transcripts per 24 hours per IP address; a free account gets 24. Captioned videos return in seconds; videos without captions are transcribed with Whisper (guests: at most 5 per 24 hours).

  1. Open https://tubetranscript.io in a browser.
  2. Click the "Drop a YouTube link." field.
  3. Paste a YouTube URL, for example https://www.youtube.com/watch?v=jNQXAC9IVRw; pasting starts extraction.
  4. Wait until the live progress log reports the transcript as ready.
  5. Click Download .txt to save the transcript.

A URL typed by hand instead of pasted starts extraction when you press Enter.

Transcript action Result
Download .txt Saves the transcript as a .txt file.
Copy RAG JSON Copies the timed chunks [{ start, duration, text }] to the clipboard.
Generate mindmap Builds a Mermaid mindmap of the video's topics.
Share Copies or shares the transcript page link.

Who can see transcripts extracted in the web app?

Transcripts extracted by guests and free accounts are public: each becomes an indexable transcript page under /c/<channel>/<video>. Transcripts extracted by Pro teams stay private to the team. Do not submit a video through a free account if its transcript page must stay unlisted. Retention details are in Security & Rate Limits.

Extracted by Visibility URL
Guest Public, indexable /c/<channel>/<video>
Free account Public, indexable /c/<channel>/<video>
Pro team Private to the team Dashboard only

How do I get an API key?

API keys require the Pro plan. Sign in, upgrade at /pricing, then create a key at /dashboard/api. Keys start with tt_live_ followed by 32 characters and are shown exactly once, so store the key in a secret manager or environment variable such as TUBETRANSCRIPT_API_KEY immediately after creating it.

  1. Sign in at https://tubetranscript.io/sign-in.
  2. Open https://tubetranscript.io/pricing.
  3. Upgrade the team to the Pro plan.
  4. Open https://tubetranscript.io/dashboard/api.
  5. Create a new API key.
  6. Copy the key, which is shown only once.
  7. Store the key in the TUBETRANSCRIPT_API_KEY environment variable (command below).
export TUBETRANSCRIPT_API_KEY="tt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

How do I extract a transcript with the REST API?

Send POST https://tubetranscript.io/api/v1/extract with Authorization: Bearer <API_KEY> and a JSON body containing url. The response is a JSON envelope: success, data, error. The transcript is in data.transcript.text (plain) and data.transcript.chunks (timed). Set the client timeout to 300 seconds, because videos without captions need Whisper transcription.

  1. Set your HTTP client timeout to 300 seconds.
  2. Send the curl request below.
  3. Check that success is true in the response.
  4. Read the transcript from data.transcript.chunks.
curl -X POST https://tubetranscript.io/api/v1/extract \
  -H "Authorization: Bearer $TUBETRANSCRIPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}'

{
  "success": true,
  "data": {
    "video_id": "jNQXAC9IVRw",
    "source": "captions",
    "transcript": {
      "text": "…",
      "chunks": [{ "start": 0, "duration": 4.2, "text": "…" }]
    },
    "features": {}
  },
  "error": null
}

The full field list, AI features and error codes are in the API Reference.

What should I do when the API returns 202?

A 202 EXTRACTION_IN_PROGRESS response means the video has no captions and Whisper transcription is still running after the route's wait budget. The body contains data.job_id and the response carries Retry-After: 60. Wait that many seconds, then send the identical request again; it resumes the same job instead of transcribing twice.

  1. Read the Retry-After header value.
  2. Wait that many seconds.
  3. Send the identical request again.
  4. Repeat steps 1–3 until the response status is 200.

How do I connect TubeTranscript to an AI agent?

Connect an MCP-capable client to https://tubetranscript.io/api/mcp using the Streamable HTTP transport and the header Authorization: Bearer <API_KEY>. The server exposes the get_transcript tool, which returns clean plain text for a video_url or video_id together with a job_id. To generate hooks, mindmaps or blog drafts, also register https://tubetranscript.io/api/mcp/tools and pass that job_id to its tools. A video without captions first returns status: "processing"; the agent calls get_transcript again about a minute later. Client-specific setup for Claude Code, Cursor, Windsurf and n8n is in MCP Setup.

  1. Get a Pro API key (see "How do I get an API key?").
  2. Run the claude mcp add commands below.
  3. Start a new Claude Code session.
  4. Ask the agent for the transcript, hooks or a mindmap of a YouTube URL.
claude mcp add --transport http tubetranscript https://tubetranscript.io/api/mcp \
  --header "Authorization: Bearer $TUBETRANSCRIPT_API_KEY"
claude mcp add --transport http tubetranscript-ai https://tubetranscript.io/api/mcp/tools \
  --header "Authorization: Bearer $TUBETRANSCRIPT_API_KEY"