# YouTube Transcript & Caption API (`zenomastro/youtube-transcript-reliable`) Actor

Reliable YouTube transcripts with timestamps, language fallback, publish-date metadata, SRT/VTT export, retries, and optional proxy support.

- **URL**: https://apify.com/zenomastro/youtube-transcript-reliable.md
- **Developed by:** [Rosario Vitale](https://apify.com/zenomastro) (community)
- **Categories:** AI, Developer tools, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 successful transcripts

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Reliable API

Extract clean YouTube transcripts from watch URLs, `youtu.be` links, Shorts, Live URLs, Embed URLs, or raw video IDs. The Actor returns full text, optional timestamped segments, subtitle exports, language information, and video metadata without requiring a YouTube Data API key.

### Why use this Actor?

Transcript extraction often fails for reasons that are hard to diagnose: captions can be disabled, a preferred language can be missing, YouTube can block a datacenter IP, or a URL format can be parsed incorrectly. This Actor is designed to make those cases explicit instead of returning an empty dataset.

Each input video produces either a structured success row or a clear failure row. Failed videos are not charged as transcript results.

### Features

- Watch, `youtu.be`, Shorts, Live, Embed, and raw video-ID input
- Manual and auto-generated caption support
- Ordered language preferences
- Optional fallback to any available transcript language
- Optional YouTube transcript translation
- Full transcript text
- Timestamped caption segments
- Optional SRT and WebVTT export
- Available-language information per video
- Metadata including title, channel, duration, views, thumbnail, and publish/upload date when exposed by YouTube
- Duplicate video IDs removed within a run
- Bounded retries with exponential backoff
- Optional Apify/custom proxy support with session rotation between attempts
- Graceful abort handling
- Pay only for successfully emitted transcript rows
- Stops cleanly at the user's maximum charge limit

### Input example

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/VIDEO_ID",
    "https://www.youtube.com/shorts/VIDEO_ID"
  ],
  "languages": ["en", "it"],
  "fallbackToAnyLanguage": true,
  "includeSegments": true,
  "includeMetadata": true,
  "includeSrt": false
}
```

### Output

A successful row contains the canonical YouTube URL, selected language, whether the source captions are auto-generated, full text, segment count, optional segments/SRT/VTT, available transcript languages, metadata, and processing time.

A failed row contains `success: false`, an error type, and a concise explanation such as captions disabled, no matching transcript, age restriction, unavailable video, or an IP block.

### Language selection

By default, manually created captions are preferred because they are often better punctuated. Enable **Prefer auto-generated captions** when ASR coverage is more useful. If none of your preferred languages exist, **Fallback to any available language** can still return a transcript.

Set **Translate transcript to** to a YouTube-supported language code to request translation when that transcript is translatable.

### Metadata and publish date

When **Include video metadata** is enabled, the Actor reads the metadata YouTube exposes on the watch page. This includes the publish or upload date when available, addressing a common gap in transcript-only tools.

Metadata availability can vary by video. Transcript extraction can still succeed even if a particular metadata field is absent.

### Reliability and proxies

YouTube may block cloud or datacenter addresses. The Actor retries temporary failures and rotates proxy sessions between attempts. **Apify Proxy is enabled by default** because direct Apify cloud IPs can be blocked by YouTube; users can disable it for direct access or provide their own proxy servers.

The default proxy path uses the normal Apify proxy configuration rather than forcing residential traffic. If a row still reports `IpBlocked` or `RequestBlocked`, choose a stronger rotating proxy configuration. Residential rotation can improve reliability but may add platform usage cost.

### Pricing

The target Store price is **$0.0012 per successfully returned transcript** — about **$1.20 per 1,000 successful transcripts** — plus the small Actor start event shown in Apify's pricing panel. Failed videos are pushed for diagnosis but do not trigger the transcript charge.

This positioning is intended to stay competitive with established transcript Actors while including richer failure handling, multiple YouTube URL forms, publish-date metadata, subtitle exports, and proxy-aware retries.

### Limits and responsible use

Maximum input is 100 videos per run. This Actor retrieves captions made available by YouTube; it does not bypass private-video access controls or account authentication. Age-restricted videos may remain unavailable because anonymous cookie authentication is not currently supported by the underlying transcript method.

Use transcripts in accordance with applicable copyright, privacy, and platform rules.

### Support

For a reproducible issue, include the public video URL, requested language settings, whether a proxy was enabled, and the run ID. Never post private proxy credentials or API tokens in an issue.

# Actor input Schema

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

YouTube watch, youtu.be, Shorts, Live, Embed URLs, or raw 11-character video IDs. Maximum 100 per run.

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

Ordered language preferences such as en, it, es. Human captions are preferred unless Prefer auto-generated is enabled.

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

If none of the preferred languages exist, use another available transcript instead of failing.

## `preferAutoGenerated` (type: `boolean`):

Prefer YouTube ASR captions over manually created captions when both are available.

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

Optional YouTube translation target language code such as en, it, es, fr. Leave blank for no translation.

## `includeSegments` (type: `boolean`):

Include each caption segment with start time and duration.

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

Fetch title, channel, thumbnail, duration, view count and publish/upload date when YouTube exposes them.

## `includeSrt` (type: `boolean`):

Return the transcript as an SRT subtitle string.

## `includeVtt` (type: `boolean`):

Return the transcript as a WebVTT subtitle string.

## `preserveFormatting` (type: `boolean`):

Preserve supported YouTube caption HTML formatting where available.

## `requestTimeoutSecs` (type: `integer`):

Maximum time allowed for a single transcript attempt.

## `retries` (type: `integer`):

Retry temporary failures with backoff. Proxy sessions rotate between attempts when proxying is enabled.

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

Apify Proxy is enabled by default for cloud reliability. Disable it for direct access or supply custom proxy servers.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "languages": [
    "en"
  ],
  "fallbackToAnyLanguage": true,
  "preferAutoGenerated": false,
  "translateTo": "",
  "includeSegments": true,
  "includeMetadata": true,
  "includeSrt": false,
  "includeVtt": false,
  "preserveFormatting": false,
  "requestTimeoutSecs": 25,
  "retries": 2,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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 = {};

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

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

```

## MCP server setup

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

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/n1McARqABW40ReKd4/builds/yvXsGiGcxN9Uz2Lmg/openapi.json