# YouTube Transcript API — Videos, Channels, Playlists, SRT/VTT (`sherwood/youtube-transcript-batch`) Actor

Bulk YouTube transcripts and subtitles from video, Shorts, channel and playlist URLs, or another Actor's dataset. One item per video: timestamped segments, text, SRT, VTT, language choice. $1 per 1,000 videos on the free plan, from $1 on paid plans; no captions = free. For n8n, Make, MCP agents.

- **URL**: https://apify.com/sherwood/youtube-transcript-batch.md
- **Developed by:** [Sherwood](https://apify.com/sherwood) (community)
- **Categories:** Videos, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 video transcripts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 — transcripts and subtitles in bulk, $1 per 1,000 videos on the free plan, from $1 on paid plans

Give it YouTube video, Shorts, channel or playlist URLs (or bare video IDs) and get one dataset item per video with the
transcript as timestamped segments and plain text, plus SRT and WebVTT on demand, in the language you prefer or
machine-translated. Videos without captions are reported and **not charged**. Nothing is required: the default input
runs alone in a few seconds.

Built for agents and workflows (MCP, n8n, Make, the API): a list in, a flat item per video out, the field names of the
most used YouTube transcript Actor (`video_id`, `language_code`, `is_generated`, `timestamped`, `non_timestamped`...),
so a workflow written for it keeps working.

### What you get

One item per video. A successful item (`outputFormats: ["json", "text", "srt"]`, trimmed):

```json
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_id": "dQw4w9WgXcQ",
  "source": null,
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "channel_name": "Rick Astley",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channel_url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "video_duration_seconds": 213,
  "view_count": 1834994377,
  "thumbnail_url": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/sddefault.webp",
  "was_live": false,
  "language": "English",
  "language_code": "en",
  "is_generated": false,
  "is_translatable": true,
  "translation_languages": ["ar", "zh-Hant", "nl", "en", "fr", "de", "hi", "id", "it", "ja", "ko", "..."],
  "translated_to": null,
  "translation_error": null,
  "source_type": "Manual",
  "snippet_count": 61,
  "total_seconds": 211.32,
  "duration_human": "3m 31s",
  "timestamped": [
    {"text": "[♪♪♪]", "start": 1.36, "duration": 1.68},
    {"text": "♪ We're no strangers to love ♪", "start": 18.64, "duration": 3.0}
  ],
  "non_timestamped": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ ...",
  "srt": "1\n00:00:01,360 --> 00:00:03,040\n[♪♪♪]\n\n2\n...",
  "vtt": null,
  "available_transcripts": [{"language": "English", "language_code": "en", "is_generated": false, "is_translatable": true}],
  "status": "ok",
  "success": true,
  "error": null,
  "error_type": null,
  "timestamp": "2026-11-08T09:36:51+00:00"
}
```

A video without a usable transcript keeps the same fields, with `status: "skipped"` (or `"error"`), `success: false`,
`error_type` and `error` saying why, and `available_transcripts` listing what YouTube does offer, so a second run with the
right `languages` gets it:

| `status` | `error_type` | Meaning | Charged |
|---|---|---|---|
| `skipped` | `TranscriptsDisabled` | YouTube lists no caption track (Shorts without captions, ongoing live streams, music without lyrics) | no |
| `skipped` | `NoTranscriptFound` | tracks exist, none in your `languages` / `transcriptType`; see `available_transcripts` | no |
| `skipped` | `VideoUnavailable`, `AgeRestricted` | private, removed, blocked in the US, or sign-in required | no |
| `error` | `PoTokenRequired`, `BotCheck`, `RateLimited`, `RequestFailed` | YouTube refused this request; try again later | no |

`source` names the channel or playlist entry a video came from (`null` for a video given directly).

### Input

| Field | Type | Default | What it does |
|---|---|---|---|
| `videoUrls` | array or string | 2 example videos | Video URLs (watch, youtu.be, Shorts, live, embed), bare 11-character IDs, channel URLs or `@handles` (Videos tab, newest first), playlist URLs. A string is split on commas and new lines. Aliases merged: `videoUrl`, `urls`, `startUrls`, `youtube_url`, `videoIds`, `channel`, `playlist`. |
| `languages` | array | `[]` | ISO 639-1 codes in order of preference (`"en"`, `"fr"`, `"pt-BR"`). First available wins, manual before auto-generated. Empty: the video's own language. |
| `transcriptType` | `any` / `manual` / `generated` | `any` | Which caption tracks to consider. |
| `translateTo` | string | — | ISO code of YouTube's machine translation of the chosen track. **Best effort**: YouTube refused every translation in our tests (HTTP 429, see Limits); the original track is then returned with `translation_error` set. |
| `outputFormats` | array of `json`, `text`, `srt`, `vtt` | `["json", "text"]` | `json` fills `timestamped`, `text` fills `non_timestamped`, `srt` and `vtt` fill the subtitle strings. |
| `includeMetadata` | boolean | `true` | Title, channel, duration, views, thumbnail: free, from the same YouTube response. |
| `maxVideosPerSource` | integer | 100 | Videos listed per channel (newest first) or playlist, up to 5,000. |
| `maxVideos` | integer | 1,000 | Unique videos per run, over all sources. |
| `datasetId` | dataset | — | Transcribe the videos listed in another Actor's dataset (a channel or search scraper). The URL or ID is read from `urlField`, else found among `url`, `videoUrl`, `video_url`, `youtube_url`, `videoId`, `video_id`, `link`, `id`. |
| `urlField` | string | — | Dotted path of the video URL inside each dataset item (`"video.url"`). |

When any alias, channel, playlist or `datasetId` is given, the two example videos of `videoUrls` are dropped: you never
pay for them by accident.

```json
{
  "videoUrls": ["https://www.youtube.com/watch?v=UF8uR6Z6KLc", "@veritasium", "https://www.youtube.com/playlist?list=PL8dPuuaLjXtNlUrzyH5r6jN9ulIgZBpdo"],
  "maxVideosPerSource": 20,
  "languages": ["en", "fr"],
  "outputFormats": ["json", "text", "srt"]
}
```

### Pricing

- **Transcript fetched** — per transcript saved, whatever the video length: a five-hour lecture costs the same as a Short.
  The price depends on your Apify plan: **$0.001 on the free plan ($1 per 1,000)**, $0.0015 on Starter, $0.0012 on Scale,
  $0.001 on Business and above — the store page shows yours.
- **Actor start** — $0.00005 per run (Apify's standard start event).
- Skipped videos (no captions, unavailable, age-restricted) and failed requests: **free**. The platform's usage (compute,
  proxies, storage) is included; nothing else is charged.

| Plan | Per transcript | Per 1,000 |
|---|---|---|
| Free | $0.001 | $1.00 |
| Starter | $0.0015 | $1.50 |
| Scale | $0.0012 | $1.20 |
| Business and above | $0.001 | $1.00 |

Set a maximum cost per run in Apify and the Actor stops cleanly when it is reached: it transcribes as many videos as the
budget allows, in input order, and says so in the run's status.

### Via API, Python, n8n, Make or MCP

- **API**: `POST https://api.apify.com/v2/acts/sherwood~youtube-transcript-batch/run-sync-get-dataset-items?token=...`
  with the input as JSON body returns the items when the run ends (a few seconds for a handful of videos).
- **Python**: `ApifyClient(token).actor("sherwood/youtube-transcript-batch").call(run_input={...})`, then
  `client.dataset(run["defaultDatasetId"]).list_items().items`.
- **n8n / Make**: the Apify node, Actor `sherwood/youtube-transcript-batch`, input as above; read the dataset items in the
  next node. Give the node 512 MB or more.
- **MCP** (Claude, Cursor, ChatGPT...): connect `https://mcp.apify.com`, then ask for the transcript of a video, a channel's
  last 20 videos or a playlist: the agent fills `videoUrls` and reads the items.
- **Chaining**: run a YouTube channel or search scraper first, then this Actor with its `datasetId` (an integration on the
  first Actor's run does it automatically).

### Use it from an AI coding agent

Install the task skill for Claude Code, Codex, Cursor, Gemini CLI or any agent that reads the Agent Skills format:

```bash
npx skills add maxouf/sherwood-skills --skill youtube-transcript
```

The skill compares this Actor with the other tools for the task, estimates the cost before running, caps the spend and hands back the result as a file. The pipeline skill `apify-competitor-watch` chains it with the other Actors of the use case. Source: [github.com/maxouf/sherwood-skills](https://github.com/maxouf/sherwood-skills).

### Run it on a schedule

Channels keep publishing. Create a [schedule](https://docs.apify.com/platform/schedules) on this Actor, or on a saved task
holding your channel and language settings — Apify's one-minute video shows how: [Schedule your Actor](https://www.youtube.com/watch?v=1jI7WcVQmwM).
With a channel URL and `maxVideosPerSource` set to the number of videos published between two runs, each run transcribes
the newest videos; deduplicate on `video_id` in your destination. To run it automatically after a channel or search
scraper instead, use the Integrations tab with `datasetId` ([video: Actor-to-Actor integration](https://www.youtube.com/watch?v=zExnYbvFoBM)).

### Limits

- Transcripts come from YouTube's own caption tracks (manual or auto-generated). A video without any track is `skipped`:
  no speech-to-text is run.
- YouTube serves caption lists to mobile clients without the proof-of-origin token it demands from browsers; a video for
  which it demands one anyway (`exp=xpe`) is returned as `error: PoTokenRequired`. If YouTube extends that requirement, the
  Actor will need an update: check `status` and `error_type` in your workflow rather than assuming success.
- Machine translation (`translateTo`) is rate-limited by YouTube per IP: on 2026-11-08 it refused every translation we
  asked for (HTTP 429), from datacenter and residential IPs alike. The original track is returned, `translated_to` stays
  `null` and `translation_error` explains. Count on it as a bonus, not as a feature; a translation step in your own
  workflow (an LLM on `non_timestamped`) is the reliable path.
- Videos blocked in the United States, private, removed or age-restricted are `skipped` with YouTube's reason.
- Channel listing reads the Videos tab (uploads, newest first), not Shorts or live tabs; use playlist URLs for those.
- Items are capped by Apify at 9 MB: for a very long video (tens of hours) the subtitle strings and then the segments are
  left out, with `non_timestamped` kept.

### Related Actors

- [Text to Speech API](https://apify.com/sherwood/text-to-speech-batch) — the other way round: turn text (a transcript, a summary) into audio with subtitles.
- [Review Analyzer](https://apify.com/sherwood/review-analyzer) — AI verdicts on any dataset of texts, transcripts included, through `datasetId`.
- [Google Maps Scraper](https://apify.com/sherwood/google-maps-scraper) — places and leads, in the fields of the most used Maps scraper.
- [YouTube Scraper](https://apify.com/streamers/youtube-scraper) and [YouTube Channel Scraper](https://apify.com/streamers/youtube-channel-scraper) — two common sources of video URLs to feed in through `datasetId`.

### FAQ

**Which language do I get when `languages` is empty?** The video's own caption track: the first manual one, else the
first auto-generated one. `language_code` and `is_generated` say which.

**Can I get all languages of one video?** One run per language today; `available_transcripts` lists them.

**Is a channel limited?** `maxVideosPerSource` (default 100, up to 5,000) and `maxVideos` (default 1,000) cap it; the
Videos tab is read newest first.

**Why is a Short skipped?** Most Shorts have no caption track at all; `error_type: TranscriptsDisabled` means YouTube
lists none.

**Do you store my transcripts?** Only in your run's dataset, under Apify's retention for your plan.

**How many videos per run?** Up to `maxVideos` (default 1,000, up to 100,000); 8 videos are processed at once at the
default 512 MB, more with more memory. A 1,000-video channel takes a few minutes.

**What does a run cost me?** One `transcript-fetched` event per saved transcript ($0.001 to $0.0015 depending on your plan)
plus the $0.00005 start event. 1,000 videos on the free plan: about $1.00. Videos without captions cost nothing.

**Is it an MCP server?** It is callable through Apify's MCP server (`https://mcp.apify.com`) like every Actor of the store:
an agent passes `videoUrls` and reads the items back, no extra setup.

# Actor input Schema

## `videoUrls` (type: `array`):

One entry per line: video URLs (watch, youtu.be, Shorts, live, embed), bare 11-character video IDs, channel URLs or @handles (their Videos tab, newest first) and playlist URLs. Aliases accepted: videoUrl, urls, startUrls, youtube_url, youtubeUrls, videoIds, videoId, channel, channels, playlist (a string with commas or new lines is split). Nothing is required: the examples below run alone.

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

ISO 639-1 codes in order of preference ("en", "fr", "pt-BR"). The first available track wins, a manual track before an auto-generated one. Empty: the video's own language (first manual track, else first auto-generated track).

## `transcriptType` (type: `string`):

Which caption tracks to consider.

## `translateTo` (type: `string`):

Optional ISO 639-1 code ("es", "fr", "de") for YouTube's machine translation of the chosen track. Best effort: YouTube rate-limits translations and refused every one in our tests (HTTP 429); the original track is then returned, translated_to stays null and translation_error says why. Never charged twice.

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

What each item carries. Default: timestamped segments and plain text.

## `includeMetadata` (type: `boolean`):

Title, channel, duration, view count and thumbnail, from the same YouTube response as the captions (free, no extra time).

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

How many videos to list from each channel (newest first) or playlist. Default 100.

## `maxVideos` (type: `integer`):

Stop after this many unique videos over all sources. Default 1,000.

## `datasetId` (type: `string`):

Transcribe the videos listed in an existing dataset (a YouTube channel or search scraper, for example). The video URL or ID is read from urlField, or found among url, videoUrl, video_url, youtube_url, videoId, video_id, link, id.

## `urlField` (type: `string`):

Dotted path inside each dataset item ("video.url"). Leave empty to let the Actor find it.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "languages": [],
  "transcriptType": "any",
  "translateTo": "fr",
  "outputFormats": [
    "json",
    "text"
  ],
  "includeMetadata": true,
  "maxVideosPerSource": 100,
  "maxVideos": 1000,
  "urlField": "url"
}
```

# Actor output Schema

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

One item per video: status, metadata, chosen caption track, timestamped segments, plain text, SRT and VTT on demand.

# 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 = {
    "videoUrls": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "languages": [],
    "outputFormats": [
        "json",
        "text"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sherwood/youtube-transcript-batch").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 = {
    "videoUrls": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    ],
    "languages": [],
    "outputFormats": [
        "json",
        "text",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("sherwood/youtube-transcript-batch").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 '{
  "videoUrls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "languages": [],
  "outputFormats": [
    "json",
    "text"
  ]
}' |
apify call sherwood/youtube-transcript-batch --silent --output-dataset

```

## MCP server setup

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

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/OwoeLaZN23dvEjr2j/builds/srPrEZMTct16EUtNT/openapi.json
