Browse documentation
API reference
YouTube Transcript API
Retrieve YouTube transcript text with timestamps and a full transcript. Automatic captions are selected by default.
Build a request
The 11-character ID from the video URL, not the full URL.
Leave blank to try en-orig, then en, and return one track. Or enter one code or up to 10 distinct codes separated by commas.
https://data.flashdata.dev/v1/queries/realtimeParameters
Send source and video_id at the top level. Source options belong in params. Optional fields can be omitted.
Request body
sourcestring / Required- Set to youtube_transcript.
video_idstring / Required- The 11-character YouTube video ID, such as FUfGcZ092b0. Accepts letters, numbers, underscores and hyphens.Exactly 11 charactersDefault:
Not setAccepted format
^[A-Za-z0-9_-]{11}$ paramsobject / Optional- Settings for this request.Default:
{} callback_urlstring · nullable / Optional- 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.Default:
Not set
Caption selection
params.languagestring | array / Optional- 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.Default:
en-orig → en params.autoboolean / Optional- true selects YouTube-generated captions; false selects uploader-provided captions. This selects caption origin, not language detection or new transcription.
trueorfalseDefault:true
Response
Realtime returns status: done. Read the source output at results[0]; usage.credits records the charge.
Read segments for timestamped text and fullText for the joined transcript. Segment start and end are seconds; languageCode and isAutoGenerated identify the selected track.
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.
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))Omit language to prefer en-orig and fall back to en, returning one track. With auto=true, each requested code prefers its -orig track, then the plain code; explicit -orig and auto=false stay exact. Arrays try every requested language and return tracks and errors in order. languageCode identifies the selected track; requestedLanguageCode is included when it differs.
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.
auto defaults to true for automatic captions. Set false for uploader-provided captions. The API never switches caption sources.
The API reads existing YouTube captions; it does not generate new transcripts. The default response contains normalized JSON text; Accept can select plain text and X-Respond-With: markdown selects Markdown. languageName can be null.
Multiple languages
Send a language array to receive tracks and per-language errors. This example shows English available and Spanish unavailable.
{
"source": "youtube_transcript",
"video_id": "jNQXAC9IVRw",
"params": {
"language": [
"en",
"es"
],
"auto": true
}
}{
"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"
}
]
}All response fields
| Field | Description |
|---|---|
sourcestring | The requested API source. |
statusstring | done when the realtime request succeeds. |
created_atstring | Response creation time in ISO 8601 format. |
usage.creditsnumber | Credits charged for the request, based on your plan. |
results[0].videoIdstring | The requested video ID. |
results[0].languageCodestring | Actual selected caption track code, such as en-orig. |
results[0].languageNamestring · nullable | Language display name when available. |
results[0].requestedLanguageCodestring · optional | The requested code when it differs from languageCode, for example en when en-orig was selected. |
results[0].isAutoGeneratedboolean | Whether the selected captions were generated automatically. |
results[0].segmentsarray | Caption segments in chronological order. |
results[0].segments[].startnumber | Segment start time in seconds. |
results[0].segments[].endnumber | Segment end time in seconds. |
results[0].segments[].textstring | Caption text. |
results[0].fullTextstring | All segment text joined into a transcript. |
results[0].tracksarray · optional | For language arrays only. Available tracks in request order; each has the single-track fields listed above. |
results[0].errorsarray · optional | For language arrays only. Failed languages in request order. Empty when every track succeeds. |
results[0].errors[].languageCodestring | The requested language that failed. |
results[0].errors[].codestring | language_unavailable when the selected track does not exist; retrieval_failed when it could not be downloaded or parsed. |
results[0].errors[].messagestring | Description of the language failure. |
The fields above describe the default JSON response. JSON, plain text and Markdown formats.
Async returns one job receipt; batch returns one per video ID. Check each job's status and retrieve its results using the returned links.
Async & batch lifecycle
Submission returns a receipt, not results. Async creates one job; batch returns a separate job in queries[] for every accepted query. Track and retrieve each job independently.
Submit to data.flashdata.dev; read job status and results from api.flashdata.dev with the same X-API-Key. The linked API basics examples use Python and cURL.
1. Save the job IDs
Keep this source's request fields when switching to Async. For Batch, put each request inside the queries array of a JSON object. Save every returned job ID.
2. Check status
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: poll with a delay and respectRetry-Afterwhen present.completed: fetch results.failed: inspectjob.error.Read job.status, not the submission receipt's status.
Check status · Python and cURL
Job status API reference3. Fetch results
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsAfter completion, authenticate the result read, then fetch the 302 storage URL without your API key. Save the JSON within 24 hours of completion.
Fetch results · Python and cURL · Response formats
Result download API reference
Polling and fetching existing results do not consume query credits. A polling timeout does not cancel the job: keep its ID instead of submitting duplicate billable work. Error codes and retry behavior.
Completion webhooks
Subscribe per query
Set callback_url at the top level of an async request, or inside each query in a batch, outside params. No separate webhook-registration request is required. Realtime requests do not send callbacks.
Use a public HTTPS URL on port 443. FlashData POSTs a notification for each job reaching completed or failed; the event contains links, not the result itself.
Acknowledge and verify
Return 2xx after durably accepting the event. Deduplicate by delivery_id, also sent as X-Delivery-Id. Redirects are not followed.
Failed deliveries retry with exponential backoff, up to 8 attempts total and at most 24 hours after completion. Keep polling as a fallback.
Callbacks are unsigned. Confirm the job ID, source and terminal status through the authenticated status endpoint before processing the notification. The delivery ID is for deduplication, not proof of authenticity.
Example webhook event and fields
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_transcript",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Field | Description |
|---|---|
delivery_idstring | Stable delivery identifier. Deduplicate notifications using this value; it is also sent in the X-Delivery-Id header. |
idstring | Job ID. |
sourcestring | Requested data source. |
statusstring | completed or failed. |
linksarray | Status and result links. Notifications do not include result content or an API key. |
links[].relstring | self or results. |
links[].hrefstring | Absolute Management API URL; authenticate with your API key. |
links[].methodstring | GET. |
Bulk file processing
Upload one video ID per line and create the Bulk job with source: youtube_transcript. Shared options apply to every ID in the file.
Source options: language, auto. Put them in options when creating the Bulk job.
Retrieve the completed collection as a manifest and gzip-compressed NDJSON result parts. Data sources can also deliver result parts to your cloud storage by setting options.result_storage when creating the Bulk job. Save the manifest and parts within 24 hours after the entire Bulk job completes.
Bulk processing API · Python and cURL · Batch JSON requests
Build a Bulk workflow for this source · Pause, resume and recover
Error recovery
If the requested track is unavailable, inspect the Metadata API's transcriptLanguages and request a supported language/track type explicitly. Repeating an unavailable selection unchanged will not create that track.
Check available caption languages with Metadata. A new request uses query credits; changing a track does not modify an existing job.
For authentication, balance, request-format and rate-limit failures, use the shared error reference. A submission timeout may still have created a job; check existing work before retrying.
Step-by-step guide: Choose a transcript language and track
Pricing
| Plans | Usage ratesper 1,000 standard requests | Subscriptions | Included credits per billing period |
|---|---|---|---|
| Pay as you go | $0.50 | No monthly fee | Top up as needed |
| Micro | $0.40 | $49.00 / month | 1,000 credits ($50.00 of API usage) included |
| Starter | $0.35 | $199.00 / month | 4,000 credits ($200.00 of API usage) included |
| Pro | $0.30 | $499.00 / month | 10,000 credits ($500.00 of API usage) included |
| Scale | $0.25 | $999.00 / month | 20,000 credits ($1,000.00 of API usage) included |
| Business | $0.20 | $1,999.00 / month | 40,000 credits ($2,000.00 of API usage) included |
One account plan. Shared Credits across all three products. Usage covered by included credits is not charged again.
Current prices and plan limits