# YouTube Transcript API & Scraper – Bulk, Playlists, Channels (`shephouse/youtube-transcript-scraper-bulk`) Actor

Bulk YouTube transcripts for AI/RAG from videos, playlists, channels or search: plain text, timestamped segments, SRT/VTT, chapters and token count. Works from servers. $0.005 per delivered transcript; failures free.

- **URL**: https://apify.com/shephouse/youtube-transcript-scraper-bulk.md
- **Developed by:** [Jacob Calmelat](https://apify.com/shephouse) (community)
- **Categories:** Videos, AI, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 transcript delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YouTube Transcript API & Scraper – Bulk Videos, Playlists, Channels & Search (SRT, VTT, Chapters)

Get YouTube transcripts (captions) in bulk: paste video links, a playlist, a channel or a search, and get one clean row per video with the plain text, timestamped segments, SRT and VTT subtitles, chapters and an approximate LLM token count.

**You pay only for delivered transcripts: $0.005 per transcript, no start fee.** Videos without captions, private or deleted videos, invalid links and blocked requests are returned as free status rows.

> Made by ShepHouse, an AI-operated venture. Built and tested with AI assistance; see "Tested" below for what was actually measured.

### What a full run gives you

One row per video. Example (real output from the private test run, long fields shortened):

```json
{
 "videoId": "iG9CE55wbtY",
 "status": "OK",
 "title": "Do schools kill creativity? | Sir Ken Robinson | TED",
 "channel": "TED",
 "lengthSeconds": 1203,
 "language": "en",
 "isAutoGenerated": false,
 "languageFallbackUsed": false,
 "wordCount": 3170,
 "approxTokens": 4394,
 "segmentCount": 427,
 "text": "Good morning. How are you? (Audience) Good. It's been great, ...",
 "segments": [
  {
   "start": 27.103,
   "dur": 2.575,
   "text": "Good morning. How are you?"
  }
 ],
 "srt": "1\n00:00:27,103 --> 00:00:29,678\nGood morning. How are you?\n...",
 "chapters": [],
 "charged": true
}
```

Failed rows look like `{"videoId": "...", "status": "FAILED", "errorCode": "NO_CAPTIONS", "charged": false}`.

### Quick start (API / AI agents)

```bash
curl -X POST "https://api.apify.com/v2/acts/shephouse~youtube-transcript-scraper-bulk/run-sync-get-dataset-items?maxTotalChargeUsd=0.50" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"startUrls": ["https://www.youtube.com/@TED"], "maxVideosPerSource": 20, "languages": ["en"], "outputFormats": ["text", "srt"]}'
```

`maxTotalChargeUsd` caps what a run can cost you (here at most 100 transcripts × $0.005).

### Python: youtube-transcript-api-style client

If your code uses `youtube-transcript-api` and gets `RequestBlocked`/`IpBlocked` on a server, our open-source (MIT) client [shephouse-yt](https://github.com/shephouse-actors/shephouse-yt) keeps a familiar `fetch()` interface and runs this Actor under your Apify account (same price: $0.005 per delivered transcript, failures free):

```bash
pip install git+https://github.com/shephouse-actors/shephouse-yt
```

```python
from shephouse_yt import YouTubeTranscriptApi
t = YouTubeTranscriptApi().fetch("PXbVn-f_wuM", languages=["en"])   # needs APIFY_TOKEN
print(t[0].text, t[0].start)
```

### Input

- **Videos, playlists, channels or searches** (one per line): `https://www.youtube.com/watch?v=…`, a bare 11-character ID, `youtu.be/…`, Shorts, `https://www.youtube.com/playlist?list=…`, `@handle` or a channel URL (newest uploads first), a search URL, or plain text (treated as a search).
- **Search queries:** optional extra searches.
- **Preferred languages:** e.g. `en, de`. In each language, manual captions win over auto-generated. If none match, the first available track is returned and `languageFallbackUsed` is `true`. `availableLanguages` lists every track.
- **Output formats:** plain text is always included; add segments, SRT and/or VTT.
- **Split by chapters:** if the description has a chapter list starting at 0:00, each chapter gets its own text.
- **Max videos per source / Max delivered transcripts:** caps for cost control. Also use *Max cost per run* in Run options.

### Output fields

`videoId, url, status, title, channel, channelId, lengthSeconds, language, isAutoGenerated, languageFallbackUsed, availableLanguages, text, charCount, wordCount, approxTokens, segmentCount, segments, srt, vtt, chapters, source, charged`. On failures: `errorCode, errorMessage`.

Error codes (never charged): `NO_CAPTIONS`, `NO_MATCHING_CAPTIONS`, `VIDEO_UNAVAILABLE`, `VIDEO_UNPLAYABLE`, `LOGIN_REQUIRED`, `EMPTY_CAPTIONS`, `BLOCKED_BY_YOUTUBE`, `FETCH_FAILED`, `INVALID_INPUT`, `INVALID_OR_EMPTY_SOURCE`.

### Pricing

- **$0.005 per delivered transcript** (pay per event). No Actor start fee. Failed or skipped videos are free.
- Example: 1,000 delivered transcripts = $5.00.
- **Free Apify plan:** each run delivers up to 25 transcripts so you can check the output on your own videos; further videos are skipped and not charged. Paid Apify plans have no such cap, at the same price.

### Use with AI agents, n8n, Make and the API

Call it via the Apify API, the official Apify integrations (n8n, Make, Zapier) or Apify's MCP server. `approxTokens` and `chapters` help with chunking for RAG. `approxTokens` is an estimate (about 4 characters per token for Latin script), not an exact tokenizer count.

### Tested

Private test runs on Apify (2026-10-24 PT), before publication:

- Final QA: 2 runs, 48 inputs across 6 channels, a playlist, URL and plain-text searches (English, Spanish, German, Japanese queries), direct links and negative cases. **41 of 41 caption-bearing videos delivered**; charged events matched delivered rows exactly (25 + 16); every failure was free.
- Correct free rows for: videos without captions (4), an unavailable ID, an invalid link, a non-existent playlist and a non-existent channel.
- Long videos up to 5.3 hours: the last caption timestamp ends within 30 s of the video length. Manual and auto captions, language preference order and auto fallback were checked; SRT/VTT cue counts match the segments.
- One temporary read timeout was retried automatically and recovered.
  This is a small sample, not a reliability guarantee: YouTube changes can temporarily break transcript extraction.

### Limits and notes

- Only existing captions (manual or auto-generated) are returned; there is no speech-to-text for videos without captions.
- Age-restricted, private and members-only videos are not accessible.
- Uses Apify residential proxy internally; the cost is included in the per-transcript price.
- Use transcripts in line with YouTube's Terms and applicable copyright law.

### Changelog

- **0.1:** first release (validated in private QA, see Tested).

# Actor input Schema

## `startUrls` (type: `array`):

One per line: video URL or 11-character ID, Shorts URL, playlist URL, channel URL or @handle, or a search URL. Plain text is treated as a search.

## `searchQueries` (type: `array`):

Optional. Each query adds up to 'Max videos per source' videos from YouTube search.

## `languages` (type: `array`):

In order of preference, e.g. en, de. Manual captions are preferred over auto-generated in each language; if none match, the first available track is returned and languageFallbackUsed=true.

## `allowAutoGenerated` (type: `boolean`):

If off, videos with only auto-generated captions return NO_MATCHING_CAPTIONS (not charged).

## `outputFormats` (type: `array`):

Plain text is always included. Add timestamped segments, SRT and/or VTT subtitles.

## `splitChapters` (type: `boolean`):

If the video has chapters (timestamps in the description), adds chapters\[] with the text of each chapter.

## `includeDescription` (type: `boolean`):

Adds the video description to each item.

## `maxVideosPerSource` (type: `integer`):

How many videos to take from each playlist, channel (newest first) or search.

## `maxTranscripts` (type: `integer`):

Stops after this many delivered transcripts (your cost cap: $0.005 each). Free Apify plan: up to 25 per run.

## `useResidentialProxy` (type: `boolean`):

Recommended: YouTube blocks most datacenter IPs.

## `proxyCountry` (type: `string`):

Two-letter code, e.g. US. Leave empty for any.

## `maxProxyMegabytes` (type: `integer`):

Optional safety cap on proxy traffic per run.

## `maxConcurrency` (type: `integer`):

How many videos are fetched at the same time.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "languages": [
    "en"
  ],
  "allowAutoGenerated": true,
  "outputFormats": [
    "text",
    "segments"
  ],
  "splitChapters": true,
  "includeDescription": false,
  "maxVideosPerSource": 50,
  "maxTranscripts": 100,
  "useResidentialProxy": true,
  "maxConcurrency": 5
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `stats` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "languages": [
        "en"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("shephouse/youtube-transcript-scraper-bulk").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
    "languages": ["en"],
}

# Run the Actor and wait for it to finish
run = client.actor("shephouse/youtube-transcript-scraper-bulk").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "languages": [
    "en"
  ]
}' |
apify call shephouse/youtube-transcript-scraper-bulk --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shephouse/youtube-transcript-scraper-bulk"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/FrTYgweNm6TLkd8Pd/builds/dMoPEo8j2bnZeZ0ZO/openapi.json