# How do I extract my first YouTube transcript with TubeTranscript?

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](https://tubetranscript.io/youtube-transcript-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](https://tubetranscript.io/docs/security.md).

| 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).

```bash
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`.

```bash
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"}'
```

```json
{
  "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](https://tubetranscript.io/docs/api.md).

### 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](https://tubetranscript.io/docs/mcp.md).

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.

```bash
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"
```