# YouTube Transcript: Captions to Text with Timestamps (`variegated_binturong/youtube-transcript`) Actor

Paste YouTube links or ids and get each video's transcript from its public captions: full text, timestamped segments, language (manual, automatic or translated), title, channel, length, available languages. Proxy option for rate limits. Videos without captions never charged.

- **URL**: https://apify.com/variegated_binturong/youtube-transcript.md
- **Developed by:** [Luigi Fiano](https://apify.com/variegated_binturong) (community)
- **Categories:** Videos, AI
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 transcript rows

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: Captions to Text with Timestamps

Paste YouTube links or video ids and get one row per video with its transcript from the public captions: the full text, the segments with start time and duration, the caption language (written by the channel, automatic, or translated by YouTube), plus the title, channel, length and every caption language the video has.

### What it is for

- **Summaries and notes with an LLM**: feed the full text of a talk, a lesson, a webinar or a podcast episode.
- **Content repurposing**: quotes, blog posts, show notes and newsletters from your own videos.
- **Search and RAG**: index what is said in a list of videos, with timestamps that link back to the exact moment (`url` + `&t=` + `start`).
- **Language work**: captions in the language you choose, or translated by YouTube.

### How it works

- For each video the public player data is read (title, channel, length, caption tracks), then the chosen caption track. Two or three requests per video: no browser, no video download.
- **Language**: `languages` in order of preference; captions written by the channel come before YouTube's automatic ones (`preferManualCaptions`). If the video has none of your languages, its first caption language is used (`fallbackToAnyLanguage`) and `usedFallbackLanguage` is true.
- **Translation**: with `translateTo`, YouTube's own machine translation of the captions is returned, unless the video already has captions in that language.
- Nothing else is read: no comments, no likes, no data about viewers.
- Private, age-restricted, members-only and unavailable videos are reported in the free `ERRORS` record, never bypassed.

### When YouTube limits requests: the proxy option

YouTube limits how many requests one IP address can make, and it may limit the data-center addresses that Actors run on. When that happens, the video goes to the free `ERRORS` record with one of these reasons:

- `YouTube is limiting requests from this IP (HTTP 429)`
- `YouTube asks to sign in to confirm this is not a bot`
- `YouTube returned an empty transcript (it may be limiting requests from this IP)`

Run those videos again with the **Proxy** option on (Apify Proxy). Every video then gets its own proxy IP, and a new one each time YouTube limits it, up to `maxRetries` times. Without the proxy, the Actor makes direct requests.

### Input

| Field | What it does | Default |
|---|---|---|
| `videos` | One video id or link per line (watch, youtu.be, shorts, embed, live, m. and music. links) | required |
| `languages` | Caption languages in order of preference | `["en"]` |
| `preferManualCaptions` | Captions written by the channel before automatic ones | true |
| `allowAutoGenerated` | Use automatic captions when there are no others | true |
| `fallbackToAnyLanguage` | Use the video's first caption language when yours are missing | true |
| `translateTo` | Language code for YouTube's machine translation (empty: none) | empty |
| `includeTimestamps` | Add the segments with start time and duration | true |
| `proxyConfiguration` | Apify Proxy, for when YouTube limits requests | off |
| `concurrency`, `timeoutSecs`, `maxRetries` | Speed and resilience | 3, 30, 2 |
| `maxVideos`, `maxResults` | Safety caps (0: no limit on rows) | 1000, 0 |

```json
{
  "videos": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/jNQXAC9IVRw",
    "arj7oStGLkU"
  ],
  "languages": ["en", "es"],
  "includeTimestamps": true
}
```

### Output

One row per video. This row comes from the Actor's own test, on a sample video:

```json
{
  "type": "transcript",
  "videoId": "Ex4mpleVid0",
  "url": "https://www.youtube.com/watch?v=Ex4mpleVid0",
  "title": "How to brew pour-over coffee at home",
  "channel": "Example Coffee Channel",
  "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "durationSeconds": 412,
  "duration": "6:52",
  "language": "en",
  "languageName": "English",
  "captionsLanguage": "en",
  "isAutoGenerated": false,
  "isTranslated": false,
  "usedFallbackLanguage": false,
  "availableLanguages": [
    { "code": "en", "name": "English", "autoGenerated": false },
    { "code": "en", "name": "English (auto-generated)", "autoGenerated": true },
    { "code": "es", "name": "Spanish", "autoGenerated": false }
  ],
  "text": "Today we brew a pour-over at home. You need fresh beans and a burr grinder. Heat the water to about 94 degrees.",
  "wordCount": 23,
  "characterCount": 111,
  "segmentsCount": 3,
  "segments": [
    { "start": 0.4, "duration": 3.1, "text": "Today we brew a pour-over at home." },
    { "start": 3.5, "duration": 2.8, "text": "You need fresh beans and a burr grinder." },
    { "start": 6.3, "duration": 3.4, "text": "Heat the water to about 94 degrees." }
  ],
  "input": "https://www.youtube.com/watch?v=Ex4mpleVid0",
  "error": null,
  "scrapedAt": "2026-11-09T05:00:00.000Z"
}
```

- `language` is the language of the text you get; with a translation it is the target language and `captionsLanguage` is the language of the original captions.
- `segments` is `null` when `includeTimestamps` is off; the full `text` is always there.
- `channel` and `channelId` are the public name and id of the channel that published the video.

#### Videos that cannot be read (not charged)

A video without captions, private, age-restricted, unavailable or limited by YouTube never becomes a dataset row, so it costs nothing. It is listed with the reason in the `ERRORS` record of the key-value store (also in the Output tab):

```json
{ "type": "error", "videoId": "zzzzzzzzzz0", "input": "https://youtu.be/zzzzzzzzzz0", "url": "https://www.youtube.com/watch?v=zzzzzzzzzz0", "title": null, "error": "video unavailable (Video unavailable)", "scrapedAt": "2026-11-09T05:00:00.000Z" }
```

Other reasons you can see: `the video has no captions (no subtitles and no automatic captions)`, `no captions in the requested language(s): fr. Available: en, en (auto-generated), it`, `private video: nothing was bypassed`, `YouTube asks to sign in to watch this video (age-restricted or members-only): nothing was bypassed`, `not a YouTube video link or id`, plus the three limits listed in the proxy section.

#### Summary

The `SUMMARY` record has the run totals: `videosChecked`, `videosOk`, `videosWithError`, `limitedByYouTube`, `proxyRetries`, `rows`, `words` and `stoppedEarly`.

### Pricing

Pay per result: **$0.002 per transcript row** in the dataset ($2 per 1,000 videos). Videos without captions or that cannot be read are not charged: they go to the free `ERRORS` record. Use `maxResults` to cap the cost of a run.

### Tips

- Only need the text? Turn off `includeTimestamps`: rows get much smaller.
- Big lists: raise `concurrency` (up to 10) and the run timeout in the run options. If many videos come back limited, run them again with the proxy on.
- Shorts and live replays work when they have captions.

### Notes

- Only public data: the public player data and the public captions. No login, no cookies, no comments, no data about viewers.
- You are responsible for how you use the transcripts (copyright and YouTube's terms).
- Not affiliated with YouTube or Google. YouTube is a trademark of Google LLC.

# Actor input Schema

## `videos` (type: `array`):

One per line (spaces and commas also separate): a video id (dQw4w9WgXcQ) or any video link (watch, youtu.be, shorts, embed, live, m. and music.). Duplicates are removed; lines starting with # are comments.

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

Language codes (en, it, es, pt-BR...). The first one the video has captions in is used; en-GB also matches en.

## `preferManualCaptions` (type: `boolean`):

Within a language, use the captions uploaded by the channel before YouTube's automatic ones.

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

Use YouTube's automatic captions when a language has no others. Off: videos with only automatic captions go to the free ERRORS record.

## `fallbackToAnyLanguage` (type: `boolean`):

When the video has none of your languages, use its first caption language (usedFallbackLanguage is then true). Off: such videos go to the free ERRORS record.

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

A language code (en, it, de...). The captions are translated by YouTube's own machine translation, unless the video already has captions in that language. Empty: no translation.

## `includeTimestamps` (type: `boolean`):

Add the segments with start time and duration in seconds. The full text is always included.

## `proxyConfiguration` (type: `object`):

Off by default. Turn on the Apify Proxy when the ERRORS record says that YouTube limits requests (HTTP 429, a bot check or empty transcripts). Every video then gets its own proxy IP, and a new one when YouTube limits it.

## `concurrency` (type: `integer`):

How many videos are read at the same time.

## `timeoutSecs` (type: `integer`):

Give up on a request after this many seconds.

## `maxRetries` (type: `integer`):

How many times a request is repeated after a timeout or a 5xx answer. With the proxy on, also how many new proxy IPs a video gets when YouTube limits it.

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

Safety cap on the number of videos processed.

## `maxResults` (type: `integer`):

Stop after this many dataset rows. 0: no limit.

## Actor input object example

```json
{
  "videos": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "languages": [
    "en"
  ],
  "preferManualCaptions": true,
  "allowAutoGenerated": true,
  "fallbackToAnyLanguage": true,
  "translateTo": "",
  "includeTimestamps": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "concurrency": 3,
  "timeoutSecs": 30,
  "maxRetries": 2,
  "maxVideos": 1000,
  "maxResults": 0
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

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

No description

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

No description

## `summary` (type: `string`):

No description

## `errors` (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 = {
    "videos": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    ],
    "languages": [
        "en"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("variegated_binturong/youtube-transcript").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 = {
    "videos": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    ],
    "languages": ["en"],
    "proxyConfiguration": { "useApifyProxy": False },
}

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

```

## MCP server setup

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

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/d5GoEyXI5p8qYo9hv/builds/s6GzBHUunFHtZbGFC/openapi.json
