YouTube Transcript Scraper

Extract complete YouTube transcripts in batches without an API key, cookies, or a login.

Each successful video produces one dataset row containing:

• Full plain text
• Timestamped segments with start, duration, and end times in seconds
• Ready-to-save SRT subtitles
• Ready-to-save WebVTT subtitles
• Detected and requested language
• Available transcript languages and automatic-caption status
• Video ID, canonical URL, title, author, channel ID, duration, view count, and thumbnail when YouTube provides them

The actor accepts standard YouTube watch URLs, Shorts URLs, live URLs, embed URLs, youtu.be links, and raw 11-character video IDs. Duplicate videos are processed once.

Why use this actor?

• No YouTube Data API key
• No account, cookies, or login
• Batch input with controlled concurrency
• Language preference fallback
• Manual and automatically generated captions
• Full text plus structured segments, SRT, and VTT in one result
• Per-video diagnostics: one unavailable video does not fail the batch
• Optional proxy, disabled by default to keep costs low
• Pay only for successful transcript rows

Input

videoUrls

An array of YouTube URLs or video IDs.

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=M7lc1UVf-VE",
    "https://youtu.be/dQw4w9WgXcQ",
    "aqz-KE-bpKQ"
  ]
}

videoIds

An optional second array for raw video IDs. This is convenient for API clients that store IDs separately from URLs.

languagePreferences

BCP 47 language codes in priority order. The actor uses the first available exact or base-language match. If none match, it falls back to another available transcript instead of failing the video.

{
  "videoUrls": ["M7lc1UVf-VE"],
  "languagePreferences": ["fr-CA", "fr", "en"]
}

Reliability controls

• maxConcurrency: parallel videos, from 1 to 10. Default: 2.
• retries: retries for temporary rate limits and server errors, from 0 to 5. Default: 2.
• requestTimeoutSecs: total timeout per video, from 10 to 180 seconds. Default: 45.

Low concurrency is intentional. It reduces throttling and keeps compute usage small.

proxyConfiguration

Proxy use is optional and off by default. Direct requests are normally the most profitable option because transcript payloads are small and public. Enable Apify Proxy only when YouTube rate-limits the run IP.

Residential proxy traffic may cost more than the $0.0025 target transcript event when used inefficiently. If a proxy is enabled, the actor keeps one sticky proxy session per video so YouTube sees a consistent IP across metadata and caption requests.

Output

A successful row has this shape:

{
  "ok": true,
  "_sample": false,
  "_diagnostic": false,
  "videoId": "M7lc1UVf-VE",
  "url": "https://www.youtube.com/watch?v=M7lc1UVf-VE",
  "title": "YouTube Developers Live: Embedded Web Player Customization",
  "detectedLanguage": "en",
  "requestedLanguage": "en",
  "isAutoGenerated": false,
  "segmentCount": 42,
  "text": "Complete transcript text...",
  "segments": [
    {
      "text": "First caption",
      "start": 0.25,
      "duration": 2.5,
      "end": 2.75
    }
  ],
  "srt": "1\n00:00:00,250 --> 00:00:02,750\nFirst caption",
  "vtt": "WEBVTT\n\n00:00:00.250 --> 00:00:02.750\nFirst caption",
  "author": "Google for Developers",
  "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
  "durationSeconds": 183,
  "viewCount": 1000,
  "thumbnailUrl": "https://i.ytimg.com/...",
  "availableLanguages": [
    {
      "languageCode": "en",
      "languageName": "English",
      "isAutoGenerated": false
    }
  ]
}

Metadata fields can be null when YouTube does not expose them. Transcript fields are present for every successful row.

Charging and diagnostics

The actor calls the transcript pay-per-event charge once after each successful transcript row is stored. The intended Store price is $0.0025 per successful transcript.

These rows are never charged:

• Invalid URL or video ID diagnostics
• Private, removed, or region-blocked videos
• Videos with captions disabled or no transcript
• Rate-limit, timeout, or network diagnostics
• The explicit _sample: true row returned for an empty input

An empty/default Apify automated test exits successfully with exactly one sample row. This prevents a no-input health check from placing the actor under maintenance.

Common diagnostic codes

Code	Meaning
INVALID_VIDEO	The input is not a supported YouTube URL or video ID.
VIDEO_UNAVAILABLE	The video is private, removed, blocked, or unavailable.
TRANSCRIPT_DISABLED	The owner disabled captions.
NO_TRANSCRIPT	YouTube returned no transcript segments.
LANGUAGE_UNAVAILABLE	A requested language could not be fetched and no fallback worked.
RATE_LIMITED	YouTube throttled the run IP.
TIMEOUT	The per-video deadline expired.
NETWORK	A network or proxy request failed.

Diagnostic rows include a concise error and a practical hint. The run remains successful so valid results from the same batch are preserved.

Run locally

Node.js 20 or newer is required.

npm ci
npm test
npm run test:live

Run the actor with Apify local storage:

$apify actor:run

Or set an input in storage/key_value_stores/default/INPUT.json and run:

$npm start

The live test uses M7lc1UVf-VE by default. Override it with LIVE_VIDEO_ID.

Technical notes

The actor uses the maintained youtube-transcript-plus package and YouTube's public, undocumented caption interfaces. It retries temporary HTTP failures with exponential backoff, discovers available languages, falls back between requested languages, and normalizes subtitle timestamps itself.

Because the caption interface is undocumented, YouTube can change it. Per-video diagnostics are designed to make those changes visible without losing other batch results.

Use this actor only for videos and transcript content you are allowed to process. Respect YouTube's terms, copyright, privacy, and applicable law.