YouTube Transcript Extractor — Bulk Captions API for AI Agents & RAG Pipelines

Extract YouTube transcripts at scale and get typed JSON rows back: timestamped segments, clean plain text, and optional SRT/WebVTT subtitle files. Works with manual and auto-generated captions in 100+ languages. Built for AI agents, RAG pipelines, and automation — the full output schema is published below and enforced by the platform.

You only pay for successful transcripts. Videos with no captions, unavailable videos, and extraction failures are reported as error rows and cost nothing beyond the run start.

Why AI agents use this YouTube transcript extractor

• Deterministic typed output — every row conforms to the published dataset schema; no HTML, no parsing surprises.
• Cost-predictable — flat per-transcript event pricing; failed videos are never charged, so budget = videos × price, worst case.
• No auth, no cookies, no API keys — paste URLs, get transcripts.
• Clear error semantics — per-video error field with a human-readable reason; the run fails (exit 1) only when zero videos succeed, so partial batches still return data.
• Cost-tiered networking — each video is tried over a direct connection first (free), then the standard datacenter proxy (included in Apify plans), and only escalates to residential proxy on failure — and only if you leave residentialFallback on.

Input schema

Field	Type	Required	Default	Description
videoUrls	array of strings	yes	—	YouTube URLs (watch?v=, youtu.be, Shorts, live, embed) or bare 11-char video IDs
language	string	no	"en"	Preferred caption language (ISO code). Manual captions win over auto-generated
fallbackToAutoCaptions	boolean	no	true	Use auto-generated captions when no manual track matches
fallbackToAnyLanguage	boolean	no	true	Take any available track when the preferred language is missing
formats	array	no	[]	Add "srt" and/or "vtt" subtitle strings to each row
includeSegments	boolean	no	true	Include the timestamped segments array
residentialFallback	boolean	no	true	Escalate to residential proxy only for videos that failed direct + datacenter attempts. Residential traffic is billed to your account per GB (transcripts are tiny). Disable to guarantee zero residential cost
proxyConfiguration	object	no	datacenter	Standard proxy used from the 2nd attempt per video; 1st attempt is always a free direct connection

Output schema

One row per input video. Success rows have error absent; failure rows contain error plus whatever metadata was recoverable.

Field	Type	Description
videoId	string	11-char video ID
url	string	Canonical watch URL
title	string | null	Video title
channel	string | null	Channel name
channelId	string | null	Channel ID (UC…)
durationSeconds	number | null	Video length
viewCount	number | null	Views at scrape time
language	string	Language of the extracted track
isAutoGenerated	boolean	True for auto (ASR) captions
availableLanguages	string[]	All tracks on the video, auto tracks suffixed (auto)
text	string	Full transcript as one plain string — LLM-ready
segmentCount	number	Number of segments
segments	{start, duration, text}[]	Timestamped segments (seconds)
srt / vtt	string	Complete subtitle file content (only if requested in formats)
error	string	Failure rows only: reason. Never charged

Example success row

{
    "videoId": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
    "channel": "Rick Astley",
    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "durationSeconds": 213,
    "viewCount": 1690000000,
    "language": "en",
    "isAutoGenerated": false,
    "availableLanguages": ["en", "en (auto)", "de-DE", "ja"],
    "text": "We're no strangers to love You know the rules and so do I ...",
    "segmentCount": 61,
    "segments": [
        { "start": 18.64, "duration": 3.24, "text": "We're no strangers to love" }
    ]
}

Example failure row

{
    "videoId": "jNQXAC9IVRw",
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "title": "Me at the zoo",
    "error": "No captions in \"xx\". Available: en, de"
}

Error semantics (for retry logic)

• Invalid input (empty videoUrls): run fails immediately, exit 1, clear status message.
• Per-video failure: error row in the dataset; the run still SUCCEEDS if at least one video produced a transcript.
• All videos failed: run FAILS (exit 1) with the first failure reason in the status message — safe to alert on.
• Each video gets 3 attempts with escalating network tiers before its error row is written.

Use from AI agents (MCP)

Add this actor as a tool in Claude, Cursor, ChatGPT connectors, or any MCP client — the input schema above is the tool's parameter schema:

{
    "mcpServers": {
        "apify": {
            "url": "https://mcp.apify.com/?tools=apricot_blackberry/youtube-transcript-extractor",
            "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
        }
    }
}

Use from code

curl (synchronous — returns dataset items directly):

curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~youtube-transcript-extractor/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "language": "en"}'

JavaScript (npm i apify-client):

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/youtube-transcript-extractor').call({
    videoUrls: ['https://www.youtube.com/watch?v=dQw4w9WgXcQ'],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();

Python (pip install apify-client):

from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("apricot_blackberry/youtube-transcript-extractor").call(
    run_input={"videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items

Use from automation platforms

• n8n / Make / Zapier — use the native Apify integration and select this actor by name.
• LangChain / LlamaIndex — use the Apify tool/loader wrappers with actor id apricot_blackberry/youtube-transcript-extractor.
• Webhooks — Apify webhooks can fire on run completion (e.g. ACTOR.RUN.SUCCEEDED) to push transcripts into your own pipeline the moment a run finishes, no polling required.

Pricing

Event	When it's charged
Actor start	Once per run
Transcript extracted	Only when a transcript is successfully extracted

No captions? Video unavailable? Not charged.

FAQ

Does it work on videos without manual subtitles? Yes — it falls back to YouTube's auto-generated captions (configurable).

Does it download the video or audio? No. It reads YouTube's caption data directly — a transcript typically takes 1-2 seconds.

What about YouTube Shorts? Fully supported — paste the Shorts URL as-is.

Will I be charged proxy costs? Direct connection is tried first (free). The datacenter proxy tier is included in Apify plans. Residential is used only as a last resort per video and can be disabled entirely with residentialFallback: false.

How many videos per run? No hard limit; 5 videos are processed concurrently. Thousands per run is fine.

Changelog

• 1.1 — Published enforced output schema; cost-tiered proxy escalation (direct → datacenter → optional residential); agent/MCP integration docs.
• 1.0 — Initial release: bulk extraction, language fallbacks, SRT/VTT, metadata, success-only billing.