# Get Transcript

Extract a transcript for any public YouTube video. Optional timestamps and metadata.

Source: https://youtubetranscriptapi.com/docs/api/transcript

The Get Transcript endpoint returns the full caption track for any public YouTube video as predictable JSON. Authenticate with `Authorization: Bearer YOUR_API_KEY`. Each successful 200 response charges 1 credit; 4xx errors, 5xx errors, and 429 rate-limits never debit. A video not fetched before usually takes 10–30 seconds; videos already fetched (`X-Cache-Status: HIT`) return in about a second, so set your HTTP client timeout to at least 60 seconds. The response always includes `video_id`, `language`, and `transcript`: an array of `{ text, start, duration }` segments by default, or a single string with `format=text`.

`GET /api/v2/youtube/transcript` — 1 credit (only charged on HTTP 200)

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `video_url` (required) | `string` | — | Video ID, full youtube.com URL, or short youtu.be URL. |
| `language` | `string` | `en` | Preferred caption language code, such as en, es or de. Values longer than 12 characters are cut to 12. If the video has no track in this language, another one may come back; the response's language field says which. |
| `format` | `string` | `json` | Either json (segments) or text (single string). |
| `include_timestamp` | `boolean` | `true` | Include start and duration on each segment. |
| `send_metadata` | `boolean` | `false` | Include video title, author, and thumbnail. |

For `include_timestamp` and `send_metadata`, only `1`, `true`, `yes` and `on` (in any case) mean true. Any other non-empty value means false; leave the parameter out to get its default.

## Example request

```bash
curl -X GET "https://youtubetranscriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ&format=json&include_timestamp=true&send_metadata=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response — JSON with timestamps and metadata

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "First caption line",  "start": 0,    "duration": 4.12 },
    { "text": "Second caption line", "start": 4.12, "duration": 3.85 }
  ],
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author_name": "RickAstleyVEVO",
    "author_url": "https://www.youtube.com/@RickAstley",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
  }
}
```

## Example response — JSON without timestamps

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "First caption line" },
    { "text": "Second caption line" }
  ]
}
```

## Example response — Plain text

When `format=text`, the transcript is returned as a single string. With `include_timestamp=true`, segments are prefixed with `[start_s]`.

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "[0.0s] First caption line\n[4.12s] Second caption line"
}
```

## Latency and timeouts

A video not fetched before usually takes 10–30 seconds; videos already fetched return in about a second. Set your HTTP client timeout to at least 60 seconds. Many clients default to differently (Python `requests` waits forever unless you pass one), so set it explicitly. On serverless hosts, also give the function itself enough run time: AWS Lambda, for example, stops a function after 3 seconds unless you raise its timeout.

```python
import requests

r = requests.get(
    "https://youtubetranscriptapi.com/api/v2/youtube/transcript",
    params={"video_url": "dQw4w9WgXcQ"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,  # seconds
)
```

```javascript
const res = await fetch(
  "https://youtubetranscriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ",
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(60_000), // milliseconds
  }
);
```

If the fetch itself times out on our side you get a `408` with `Retry-After: 3`, which is not charged; retry it.

## Response headers

Every successful response carries:

- `X-Credits-Charged`: what this call cost (`1`).
- `X-Credits-Remaining`: the balance you can still spend (left out on the rare response where it can't be read reliably). Use it to alert before you run out; see [credit headers](https://youtubetranscriptapi.com/docs/rate-limits#credit-headers).
- `X-Cache-Status`: `HIT` when the transcript was already stored, `MISS` when it was fetched live. See [Caching](https://youtubetranscriptapi.com/docs/caching).
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. See [Rate Limits](https://youtubetranscriptapi.com/docs/rate-limits).

## Edge cases

- **404** — video has no captions, is private, or has been removed.
- **422** — the `video_url` didn't resolve to a valid video ID.
- **408 / 503** — transient upstream error; safe to retry after 1–5s.
