# YouTube Transcript API & Metadata Extractor (`useai/youtube-transcript-api`) Actor

Extract complete YouTube transcripts from one public video per run. Get clean text, timestamped segments, grouped Markdown, caption language, and video metadata for RAG, AI agents, search, and research. No YouTube API key or browser setup.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Transcript API & Metadata Extractor

Extract a complete transcript from one public YouTube video per run. The API returns clean text, timestamped segments, grouped Markdown, caption language, and point-in-time video metadata for RAG, AI agents, search, and research.

TubeAI is the extraction engine behind this private candidate. The product contract is deliberately narrow: one video, transcript-only, predictable output.

### What you get

| Result | Use |
| --- | --- |
| Full transcript text | RAG chunks, summaries, notes, and full-text search |
| Timestamped segments | Citations and navigation back to the video |
| Grouped Markdown | Stable context blocks for LLM prompts |
| Caption details | Requested and resolved language plus manual or auto-generated track |
| Video metadata | Title, channel, date, counts, description, thumbnail, handle, and tags when available |
| Content hash | Detect duplicate or changed transcript content |
| Structured error item | Reliable handling when captions cannot be extracted |

The transcript is not silently shortened. Metadata counters are a point-in-time snapshot, not live guarantees.

### Quick start

In Apify Console, provide one public YouTube URL, leave `language` as `auto`, choose the grouping interval, and start the run. The same input works with the API and Apify clients:

```json
{
  "videoUrls": ["https://www.youtube.com/watch?v=BYXbuik3dgA"],
  "language": "auto",
  "intervalMinutes": 2
}
```

Python:

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("scrapifiers/youtube-transcript-api").call(
    run_input={
        "videoUrls": ["https://www.youtube.com/watch?v=BYXbuik3dgA"],
        "language": "auto",
        "intervalMinutes": 2,
    },
    memory_mbytes=512,
    timeout_secs=120,
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

HTTP, n8n, and MCP integrations can call the same Apify Actor endpoint and consume the default Dataset URL. In an Apify-compatible MCP client, expose the Actor through the Apify MCP server and pass the JSON input above. Keep tokens in environment variables or platform secrets; never put them in input URLs.

### Use cases

#### Use this Actor when

- You need a transcript API for RAG, AI agents, search, research, or citation workflows.
- You need original caption timing and grouped Markdown rather than a generated summary.
- You want one stable JSON Dataset item that includes useful source metadata.
- You prefer a narrow API contract that is easy to call from Python, HTTP, n8n, or MCP.

### Do not use this Actor when

- You need comments, channel inventories, playlists, search results, audio, or video files.
- You need translation, summaries, sentiment analysis, or other generated content.
- You need a multi-video batch in one run. Start separate runs or orchestrate them externally.

### Input

Provide exactly one public YouTube video URL per run. Standard watch URLs, `youtu.be` links, Shorts, live-video URLs, and embed URLs are accepted.

| Field | Required | Description |
| --- | --- | --- |
| `videoUrls` | Yes | An array containing exactly one public YouTube video URL |
| `language` | No | Existing caption language code, or `auto`; default is `auto` |
| `intervalMinutes` | No | Deterministic Markdown group size; default is 2 minutes |

`auto` selects the first available manual caption track, then an auto-generated track. A specific language selects an existing track in that language. Captions are not translated.

### Output

Each attempted extraction produces one successful transcript item or one explicit error item in the default Dataset. A run stopped before extraction by its charge limit can contain no item.

```json
{
  "status": "ok",
  "sourceUrl": "https://www.youtube.com/watch?v=BYXbuik3dgA",
  "videoId": "BYXbuik3dgA",
  "sourceVariant": "youtube_transcript_no_comments",
  "languageRequested": "auto",
  "languageResolved": "en",
  "captionKind": "manual",
  "title": "Example video",
  "channelName": "Example channel",
  "durationSeconds": 180,
  "metadataCapturedAt": "2026-08-21T00:00:00Z",
  "publishedAt": "2026-08-20T00:00:00Z",
  "viewCount": 12345,
  "likeCount": 321,
  "commentCount": 42,
  "transcriptText": "First line. Second line.",
  "transcriptMarkdown": "[00:00:00] First line.\n[00:01:05] Second line.",
  "groupedTranscriptMarkdown": "[00:00:00] First line. Second line.\n",
  "transcriptSha256": "afe374c8081eb1b50d3b8d55b65c7785f8c68707b92564137feea31c0eb970cd",
  "segments": [{"startSeconds": 0.0, "durationSeconds": 2.0, "text": "First line."}],
  "groups": [{"startSeconds": 0, "timestamp": "00:00:00", "text": "First line. Second line."}],
  "stats": {"segmentCount": 2, "groupCount": 1, "wordCount": 4, "intervalMinutes": 2},
  "errorCategory": null,
  "errorMessage": null,
  "retryable": null
}
```

For an error item, `status` is `error`, `errorCategory` identifies the failure class, `errorMessage` is sanitized, and `retryable` indicates whether a later run may succeed.

### Limits and reliability

- One video per run; external orchestration is required for a list.
- The video must be public and have an accessible caption track.
- The extraction deadline is 105 seconds. The candidate is verified with a 120-second Actor timeout and 512 MiB memory.
- Bounded retries categorize challenges, access denials, rate limits, server errors, and transport failures; non-retryable client errors fail fast.
- A successful transcript is saved before it is counted as a successful paid result. Failed items are not counted as successful transcripts.
- Safe parallel capacity is not promised. Start with one run at a time and measure your own workload before increasing concurrency.

### Pricing

Check the current price and platform-usage treatment in Apify Console or the Store before running this private candidate. Public retail pricing is operator-gated; historical test values are not a pricing promise.

### Privacy and responsible use

The result stores a canonical YouTube watch URL and does not retain input tracking parameters or URL credentials. This Actor is not affiliated with or endorsed by YouTube. Use it only for content you are authorized to access and in accordance with applicable terms and law.

### FAQ

**Can I submit multiple videos in one run?** No. Submit one URL and start separate runs for multiple videos.

**Does it download video or audio?** No. It returns caption-derived transcript data only.

**Are comments included?** No. Comments are intentionally excluded from this transcript product.

**Can it translate subtitles?** No. Choose an existing caption language or use `auto`.

**What happens when captions are unavailable?** The Dataset receives a structured error item with a category, sanitized message, and retry guidance.

**Where are results stored?** Transcript and error items are written to the run's default Dataset and are available through Console, the Dataset API, and Apify clients.

# Actor input Schema

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

One public YouTube video URL. Channel, playlist, and search URLs are not accepted.

## `language` (type: `string`):

Use auto to select the first available manual transcript, then an auto-generated transcript. Or provide an exact YouTube caption language code such as en, es, or ru. This Actor does not silently translate captions.

## `intervalMinutes` (type: `integer`):

Group timestamped transcript text into stable Markdown sections of this many minutes.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=BYXbuik3dgA"
  ],
  "language": "auto",
  "intervalMinutes": 2
}
```

# Actor output Schema

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

Default dataset containing the transcript snapshot, optional video metadata, or categorized error item.

# 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=BYXbuik3dgA"
    ],
    "language": "auto",
    "intervalMinutes": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("useai/youtube-transcript-api").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=BYXbuik3dgA"],
    "language": "auto",
    "intervalMinutes": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("useai/youtube-transcript-api").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=BYXbuik3dgA"
  ],
  "language": "auto",
  "intervalMinutes": 2
}' |
apify call useai/youtube-transcript-api --silent --output-dataset

```

## MCP server setup

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

```

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/nbERKn0LGHecfr8Wl/builds/5bOnApOZGrQuOaD4O/openapi.json