# FlashData YouTube Transcript API

Retrieve YouTube transcript text with timestamps and a full transcript. Automatic captions are selected by default.

Canonical reference: https://flashdata.dev/docs/sources/youtube_transcript
Reviewed: 2026-10-23

Endpoint: POST https://data.flashdata.dev/v1/queries/realtime
Authentication: X-API-Key: YOUR_API_KEY
Modes: [Realtime](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/docs/reference/bulk-processing/reference.md)

Required source permission: youtube_transcript

Replace YOUR_API_KEY with an API key that has this source permission and available credits. Run requests on your server or agent host.

[Set up authentication](https://flashdata.dev/docs/guides/headers-and-authentication/reference.md)

[Choose a transcript language and track](https://flashdata.dev/docs/guides/youtube-data-guide/reference.md#captions)

<a id="quickstart"></a>

## Send a request

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_transcript",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": True,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_transcript",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": true
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parameters

<a id="parameters-group-0"></a>

### Request body

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Yes | — | Set to youtube_transcript.  |
| <a id="parameter-video_id"></a> video_id | string | Yes | Not set | The 11-character YouTube video ID, such as FUfGcZ092b0. Accepts letters, numbers, underscores and hyphens. Min length: 11. Max length: 11. Pattern: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | No | {} | Settings for this request.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No | Not set | Async and batch only. Public HTTPS completion URL on port 443, up to 2,048 characters. No user credentials or URL fragment. Omit, use null or an empty string for no notification. In a batch, set this on each query, outside params.  |

<a id="parameters-group-1"></a>

### Caption selection

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | No | en-orig → en | Omit for English (en-orig, then en). With auto=true, each code tries its -orig track first, then the requested code. Explicit -orig codes and auto=false stay exact. Arrays request 1–10 distinct languages. Omit to prefer en-orig and fall back to en, returning one track. With auto=true, each code tries its -orig track first, then the requested code; explicit -orig codes and auto=false stay exact. Arrays of 1–10 distinct codes try every requested language and return tracks and per-language errors in request order. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. |
| <a id="parameter-params-auto"></a> params.auto | boolean | No | true | true selects YouTube-generated captions; false selects uploader-provided captions. This selects caption origin, not language detection or new transcription.  |

<a id="response"></a>

## Read the result

Save the successful JSON response as response.json. Save this as read-response.py and run python read-response.py. It uses only Python's standard library and makes no new request.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Sample response

Recorded example; fields and counts depend on the source and requested input.
```json
{
  "source": "youtube_transcript",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": true,
      "segments": [
        {
          "start": 0.32,
          "end": 14.58,
          "text": "[Music]"
        },
        {
          "start": 18.8,
          "end": 25.96,
          "text": "We're no strangers to"
        },
        {
          "start": 21.8,
          "end": 29.119,
          "text": "love. You know the rules and so do"
        },
        {
          "start": 25.96,
          "end": 30.279,
          "text": "I. I feel commitments from what I'm"
        },
        {
          "start": 29.119,
          "end": 34.36,
          "text": "thinking"
        },
        {
          "start": 30.279,
          "end": 39.559,
          "text": "of. You wouldn't get this from any other"
        },
        {
          "start": 34.36,
          "end": 43.12,
          "text": "guy. I just want to tell you how I'm"
        },
        {
          "start": 39.559,
          "end": 45.84,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 43.12,
          "end": 49.2,
          "text": "Never going to give you up. I'm going to"
        },
        {
          "start": 45.84,
          "end": 53.32000000000001,
          "text": "let you down. I'm going to run around"
        },
        {
          "start": 49.2,
          "end": 56.399,
          "text": "and desert you. I'm going to make"
        },
        {
          "start": 53.32,
          "end": 59.879,
          "text": "you say goodbye."
        },
        {
          "start": 56.399,
          "end": 64.04,
          "text": "Tell a lie and hurt"
        },
        {
          "start": 59.879,
          "end": 67.2,
          "text": "you. We've known each other for so"
        },
        {
          "start": 64.04,
          "end": 70.56,
          "text": "long. Your heart's been aching, but"
        },
        {
          "start": 67.2,
          "end": 72.60000000000001,
          "text": "you're too shy to say we don't know"
        },
        {
          "start": 70.56,
          "end": 77.799,
          "text": "what's been going"
        },
        {
          "start": 72.6,
          "end": 81.479,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 77.799,
          "end": 84.56,
          "text": "play. If you ask me how I'm"
        },
        {
          "start": 81.479,
          "end": 88.32,
          "text": "feeling, don't tell me your truth. to"
        },
        {
          "start": 84.56,
          "end": 88.32000000000001,
          "text": "see. I will give"
        },
        {
          "start": 89.88,
          "end": 94.72,
          "text": "you"
        },
        {
          "start": 91.72,
          "end": 94.72,
          "text": "around"
        },
        {
          "start": 95,
          "end": 99.04,
          "text": "you. I will say"
        },
        {
          "start": 99.56,
          "end": 106.759,
          "text": "goodbye and hurt you. I will give"
        },
        {
          "start": 103.99,
          "end": 108.6,
          "text": "[Music]"
        },
        {
          "start": 106.759,
          "end": 115.92,
          "text": "you"
        },
        {
          "start": 108.6,
          "end": 115.92,
          "text": "around you. I will leave you. I will say"
        },
        {
          "start": 116.439,
          "end": 121.079,
          "text": "goodbye and hurt you."
        },
        {
          "start": 128.319,
          "end": 132.56,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 129.759,
          "end": 134,
          "text": "give."
        },
        {
          "start": 132.56,
          "end": 136.8,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 134,
          "end": 141.04,
          "text": "give."
        },
        {
          "start": 136.8,
          "end": 143.68,
          "text": "We've known each other for so long."
        },
        {
          "start": 141.04,
          "end": 147.51999999999998,
          "text": "Your heart's been aching, but you're too"
        },
        {
          "start": 143.68,
          "end": 148.52,
          "text": "shy to say it. We both know what's been"
        },
        {
          "start": 147.52,
          "end": 152.239,
          "text": "going"
        },
        {
          "start": 148.52,
          "end": 157.8,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 152.239,
          "end": 161.36,
          "text": "play it. I just want to tell you how I'm"
        },
        {
          "start": 157.8,
          "end": 163.92000000000002,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 161.36,
          "end": 166.8,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 163.92,
          "end": 171.28,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 166.8,
          "end": 171.28,
          "text": "around and desert you. Heat."
        },
        {
          "start": 172.33,
          "end": 182.76,
          "text": "[Music]"
        },
        {
          "start": 178.76,
          "end": 182.76,
          "text": "Heat. Heat. Heat."
        },
        {
          "start": 183.39,
          "end": 195.2,
          "text": "[Music]"
        },
        {
          "start": 191.04,
          "end": 197.76,
          "text": "Never going to tell a lie and hurt you."
        },
        {
          "start": 195.2,
          "end": 200.64,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 197.76,
          "end": 204.239,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 200.64,
          "end": 206.83999999999995,
          "text": "around and desert you. Never going to"
        },
        {
          "start": 204.239,
          "end": 211.879,
          "text": "make you cry. Never going to say"
        },
        {
          "start": 206.84,
          "end": 211.879,
          "text": "goodbye. Never going to say goodbye."
        }
      ],
      "fullText": "[Music] We're no strangers to love. You know the rules and so do I. I feel commitments from what I'm thinking of. You wouldn't get this from any other guy. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. I'm going to let you down. I'm going to run around and desert you. I'm going to make you say goodbye. Tell a lie and hurt you. We've known each other for so long. Your heart's been aching, but you're too shy to say we don't know what's been going on. We know the game and we're going to play. If you ask me how I'm feeling, don't tell me your truth. to see. I will give you around you. I will say goodbye and hurt you. I will give [Music] you around you. I will leave you. I will say goodbye and hurt you. Never going to give. Never going to give. Never going to give. Never going to give. We've known each other for so long. Your heart's been aching, but you're too shy to say it. We both know what's been going on. We know the game and we're going to play it. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. Never going to let you down. Never going to run around and desert you. Heat. [Music] Heat. Heat. Heat. [Music] Never going to tell a lie and hurt you. Never going to give you up. Never going to let you down. Never going to run around and desert you. Never going to make you cry. Never going to say goodbye. Never going to say goodbye."
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:44.040Z"
}
```

## Multiple languages

Send a language array to receive tracks and per-language errors. This example shows English available and Spanish unavailable.

```json
{
  "source": "youtube_transcript",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": true
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": true,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en-orig",
      "requestedLanguageCode": "en",
      "languageName": null,
      "isAutoGenerated": true,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Auto-generated subtitles not available for language: es"
    }
  ]
}
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| source | string | The requested API source. |
| status | string | done when the realtime request succeeds. |
| created_at | string | Response creation time in ISO 8601 format. |
| usage.credits | number | Credits charged for the request, based on your plan. |
| results[0].videoId | string | The requested video ID. |
| results[0].languageCode | string | Actual selected caption track code, such as en-orig. |
| results[0].languageName | string · nullable | Language display name when available. |
| results[0].requestedLanguageCode | string · optional | The requested code when it differs from languageCode, for example en when en-orig was selected. |
| results[0].isAutoGenerated | boolean | Whether the selected captions were generated automatically. |
| results[0].segments | array | Caption segments in chronological order. |
| results[0].segments[].start | number | Segment start time in seconds. |
| results[0].segments[].end | number | Segment end time in seconds. |
| results[0].segments[].text | string | Caption text. |
| results[0].fullText | string | All segment text joined into a transcript. |
| results[0].tracks | array · optional | For language arrays only. Available tracks in request order; each has the single-track fields listed above. |
| results[0].errors | array · optional | For language arrays only. Failed languages in request order. Empty when every track succeeds. |
| results[0].errors[].languageCode | string | The requested language that failed. |
| results[0].errors[].code | string | language_unavailable when the selected track does not exist; retrieval_failed when it could not be downloaded or parsed. |
| results[0].errors[].message | string | Description of the language failure. |

- The API reads captions already available on YouTube. It does not generate new transcripts or fall back between automatic and uploader-provided captions.
- A string language keeps the single-track response. An array, even ["en"], returns tracks and errors instead of top-level languageCode, segments and fullText. Each track includes those fields. auto applies to every language.
- For language arrays, check errors for tracks that failed. If no tracks are retrieved, the request fails and any reserved credits are refunded. Video extraction failures and request deadline expiry also fail the request.
- Available for realtime, async, batch and bulk. Bulk exports stay JSONL with one record per video, including its tracks and errors. Accept and X-Respond-With apply as usual.

## Response formats

Responses use JSON by default. Choose another format with these optional headers.

- Accept: application/json (default) or text/plain. Plain text presents the same fields in a readable, indented layout.
- X-Respond-With: markdown. Leave unset for original fields. Markdown works with either response format.

Markdown is available for realtime queries and completed results.

The fields below describe the default JSON response.

[Request and response format examples](https://flashdata.dev/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## API basics

The request builder and examples above use this source's parameters. Use the Python and cURL examples below for shared submission, status and result steps. A Batch body is a JSON object containing queries; each item returns its own job ID.

- [Async request and receipt](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Check job status](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Retrieve completed results](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON requests](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch)
- [Bulk processing API](https://flashdata.dev/docs/reference/bulk-processing/reference.md)
- [Build a Bulk workflow for this source](https://flashdata.dev/docs/reference/bulk-processing/reference.md?source=youtube_transcript#playground)
- [Customer OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Completion notifications

- [Receive and verify completion webhooks](https://flashdata.dev/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Troubleshooting

- [Errors and status codes](https://flashdata.dev/docs/errors/reference.md#status-codes)
- [When to retry](https://flashdata.dev/docs/errors/reference.md#retries)

## Related APIs

- [YouTube Captions API](https://flashdata.dev/docs/sources/youtube_captions/reference.md)
- [YouTube Video Metadata API](https://flashdata.dev/docs/sources/youtube_metadata/reference.md)
