# YouTube Transcript Scraper: Videos, Channels & Playlists (`ytapi/youtube-transcript-scraper`) Actor

Get transcripts of YouTube videos, whole channels and playlists (up to 5,000 videos each) in one run. Plain text, Markdown, SRT, VTT or timed segments, with optional word timestamps. You pay only for videos that return a transcript.

- **URL**: https://apify.com/ytapi/youtube-transcript-scraper.md
- **Developed by:** [YTAPI](https://apify.com/ytapi) (community)
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 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 Scraper: Videos, Channels & Playlists

Get the transcripts (captions) of YouTube videos, including a whole channel or playlist in one run: up to 5,000 videos per channel or playlist. Paste video links, channels or playlists, and the Actor returns one dataset item per video with the transcript as plain text, Markdown, SRT, WebVTT or timed segments, with optional word-level timestamps.

You are charged only for videos that come back with a transcript. Videos without captions, unavailable videos and failed fetches are listed in the dataset for free.

### What it does

- Accepts video URLs (`watch`, `youtu.be`, Shorts, live, embed) and 11-character video IDs.
- Accepts channels as URLs, `@handles` or channel IDs (`UC...`), and lists their newest uploads. Choose regular videos or Shorts.
- Accepts playlists as URLs or playlist IDs (`PL...`), in playlist order.
- Takes up to *Max videos per channel or playlist* from each channel or playlist.
- Processes each video once, even if it appears in several inputs.
- Uses the creator's captions when they exist and YouTube's auto-generated captions otherwise.
- Lets you set preferred languages, for example `en,*` (English if available, otherwise the video's own language).

### Input

| Field | Description | Default |
| --- | --- | --- |
| `startUrls` | Videos, channels or playlists, one per line. Required. | |
| `maxVideosPerSource` | Videos to take from each channel or playlist (1 to 5,000). | `100` |
| `channelTab` | `videos` or `shorts`. A channel URL ending in `/videos` or `/shorts` overrides it for that channel. | `videos` |
| `format` | `text`, `markdown`, `srt`, `vtt` or `segments`. | `text` |
| `languages` | Comma-separated language codes in order of preference. `*` means the language spoken in the video. | video's own language |
| `wordTimestamps` | Adds each word's start time to every segment. Needs `format: segments`. Only YouTube's auto-generated captions have word timings; `hasWordLevel` tells you which videos got them. | `false` |

Example input:

```json
{
    "startUrls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://www.youtube.com/@TED",
        "https://www.youtube.com/playlist?list=PLOGi5-fAu8bEGMnNkrJooL04E5zlkvDjc"
    ],
    "maxVideosPerSource": 20,
    "format": "text",
    "languages": "en,*"
}
```

Legacy channel URLs (`/c/name`, `/user/name`) are not accepted; use the channel's `@handle` or its `/channel/UC...` URL. A `watch` link that also carries a playlist (`&list=...`) is treated as that one video; to get the whole playlist, use its `playlist?list=...` URL.

### Output

One item per video. Example from a test run with `format: "markdown"` (transcript shortened):

```json
{
    "videoId": "4qxROUatTzk",
    "url": "https://www.youtube.com/watch?v=4qxROUatTzk",
    "title": "The Science of Learning New Things | Tania Lombrozo | TED",
    "source": "https://www.youtube.com/@TED",
    "status": "ok",
    "errorCode": null,
    "errorMessage": null,
    "language": "en",
    "trackKind": "manual",
    "durationSeconds": 938,
    "transcript": "# Transcript: 4qxROUatTzk\n\n### [0:00]\nSoftware engineers have a delightful\npractice called rubber ducking. When they run into a problem\nwith their code, they'll…",
    "segments": null,
    "fetchedAt": "2026-11-16T07:47:08.979Z"
}
```

With `format: "segments"`, `transcript` is `null` and `segments` holds the timed lines:

```json
"segments": [
    { "text": "What you're doing,", "start": 1.579, "end": 3.329, "duration": 1.75 }
]
```

Fields:

- `status`: `ok` (transcript delivered), `no_captions` (no captions, or none in the requested languages), `unavailable` (for example deleted, private, members-only or region-blocked), `failed` (could not be fetched after several retries; running it again later may work).
- `errorCode` and `errorMessage`: why a video has no transcript.
- `language`: language code of the captions returned.
- `trackKind`: `manual` (uploaded by the creator) or `asr` (auto-generated by YouTube).
- `title`: filled for videos that came from a channel or playlist; `null` for single video links.
- `durationSeconds`: video length from the channel or playlist listing, or the caption length for the `segments` format; `null` when unknown.

You can download the dataset as JSON, CSV, Excel or HTML from the run's Storage tab.

### Pricing

This Actor uses pay-per-event pricing. You pay a fixed price for each transcript delivered (each item with `status: "ok"`). Items with `no_captions`, `unavailable` or `failed` cost nothing. Listing channels and playlists costs nothing either.

If you set a maximum cost for the run, the Actor stops when the next transcript would go over it.

### Free plan limit

On the Apify free plan, a run delivers at most **100 transcripts**. When the limit is reached the run stops, the log and status message say so, and the remaining videos are not processed. Paid Apify plans have no such limit.

### Limits

- Only videos that have captions on YouTube (creator-uploaded or auto-generated) get a transcript. The Actor does not transcribe audio, so videos without captions return `no_captions`.
- Age-restricted, members-only, private and deleted videos have no transcript. They are listed with status `unavailable` (or `failed`) and are not charged.
- Captions are returned in the languages YouTube has for the video. The Actor does not translate.
- Live streams that are still running have no transcript yet.
- Channels list public uploads only; Shorts listings have no duration.

# Actor input Schema

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

One per line. Accepted: video URLs (watch, youtu.be, Shorts, live, embed) or 11-character video IDs; channel URLs, @handles or channel IDs (UC...); playlist URLs or playlist IDs (PL...). A channel URL ending in /shorts lists that channel's Shorts. Duplicate videos are processed once. On the free Apify plan a run delivers at most 100 transcripts; paid plans have no such limit.

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

How many videos to take from each channel or playlist (newest first for channels, playlist order for playlists). Single video URLs are not affected. On the free Apify plan the run still stops after 100 transcripts in total.

## `channelTab` (type: `string`):

Which uploads to list for channels: regular videos or Shorts. A channel URL that ends in /videos or /shorts overrides this for that channel.

## `format` (type: `string`):

text: plain text. markdown: paragraphs under timestamp headings, with chapter headings when the video has chapters. srt / vtt: subtitle files. segments: a list of timed segments (text, start, end, duration in seconds) in the "segments" field instead of "transcript".

## `languages` (type: `string`):

Optional. Comma-separated language codes in order of preference, for example "en,*" or "es,pt-BR". "*" means the language spoken in the video. Leave empty to get the video's own language. If none of the listed languages exists, the video is returned with status no_captions and is not charged. Captions are never machine-translated.

## `wordTimestamps` (type: `boolean`):

Adds the start time of each word to every segment. Needs the segments format. Only YouTube's auto-generated captions have word timings; creator captions return segment timings only (hasWordLevel is false).

## Actor input object example

```json
{
  "startUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "maxVideosPerSource": 100,
  "channelTab": "videos",
  "format": "text",
  "languages": "en,*",
  "wordTimestamps": false
}
```

# Actor output Schema

## `transcripts` (type: `string`):

All dataset items, one per video, including videos that returned no transcript.

# 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"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ytapi/youtube-transcript-scraper").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"] }

# Run the Actor and wait for it to finish
run = client.actor("ytapi/youtube-transcript-scraper").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"
  ]
}' |
apify call ytapi/youtube-transcript-scraper --silent --output-dataset

```

## MCP server setup

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

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/MpLddeubFcBqrVeNd/builds/P1x8e96czWcWtHGrg/openapi.json
