# YouTube Transcript Scraper – Video Captions & Subtitles by URL (`endspec/youtube-instant-transcript-scraper`) Actor

Extract the full transcript of any YouTube video by URL or ID: timestamped caption segments plus clean, joined plain text. Batch many videos in one run. No login, no cookies, no YouTube API key. Pay only per transcript returned.

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

## Pricing

from $6.50 / 1,000 transcript returneds

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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 Scraper — Get Video Captions & Subtitles by URL

Extract the full **YouTube transcript** of any video by URL or ID. This YouTube transcript scraper returns timestamped caption segments **and** clean, joined plain text, and can process a whole list of videos in one run. No login, no cookies, no YouTube Data API key — paste a link and get the transcript.

### Quick start (input → output)

**Input:**
```json
{ "videos": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "lang": "en" }
````

**Output (one row per video):**

```json
{
  "videoId": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "en",
  "text": "[Music] We're no strangers to love. You know the rules and so do I...",
  "segments": [
    { "startTime": "0:00", "startMs": 320, "text": "[Music]" },
    { "startTime": "0:18", "startMs": 18560, "text": "We're no strangers to love" }
  ],
  "segmentCount": 52,
  "durationSeconds": 212
}
```

### What this actor does

- Accepts one or many YouTube videos (`watch?v=`, `youtu.be/`, `/shorts/`, or a bare 11-char ID).
- Returns, per video: the ordered transcript **segments** (with start time), the full transcript as one **plain-text** string, the segment count, and the video duration.
- Optional preferred `lang`; falls back to the video's default language when the requested one isn't published.

### Input parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `videos` | array of strings | ✅ | YouTube video URLs or 11-character IDs. One transcript per video. |
| `lang` | string | — | Preferred 2-letter language code (e.g. `en`, `es`, `de`). Blank = default. |

**Important notes**

- One row is produced per input video. Videos with captions disabled return an error row (and are **not** charged).
- `lang` is a preference, not a guarantee — if unavailable, the default transcript is returned.

#### More input examples

```json
{ "videos": ["dQw4w9WgXcQ", "https://youtu.be/9bZkp7q19f0"] }
```

```json
{ "videos": ["https://www.youtube.com/shorts/abc123DEF45"], "lang": "es" }
```

### Output

#### Field reference

| Field | Description |
|---|---|
| `videoId` | The 11-character YouTube video ID. |
| `url` | Canonical watch URL. |
| `language` | Language requested (`default` if none given). |
| `text` | Full transcript as a single normalized string. |
| `segments` | Array of `{ startTime, startMs, text }` in order. |
| `segmentCount` | Number of caption segments. |
| `durationSeconds` | Transcript end time in seconds. |

#### Output examples

**Empty / no captions** (not charged):

```json
{ "status": "error", "error": "No transcript is available for this video (captions may be disabled). You were not charged.", "_query": "{\"input\":\"...\",\"lang\":null}" }
```

**Bad input** (not charged):

```json
{ "status": "error", "error": "That input is not a valid YouTube video URL or ID. Please check it and try again. You were not charged." }
```

**Service busy / temporary** (not charged):

```json
{ "status": "error", "error": "The transcript service is temporarily unavailable — please retry shortly. You were not charged." }
```

### Use cases

- **Content & SEO:** turn videos into blog posts, summaries, and searchable text.
- **Researchers / students:** read and quote long talks and lectures without watching in full.
- **AI / LLM pipelines:** feed clean transcripts to summarizers, RAG, or translation.
- **Accessibility:** produce readable captions and text alternatives.

### Best practices

- Batch many videos in one run instead of one run per video.
- Pass IDs directly when you already have them — it's the same result.
- Expect an error row (unbilled) for private, region-locked, or caption-disabled videos.

### Pricing

Pay-per-event: you are charged **once per transcript returned**. Error rows (no captions, bad input, temporary failures) are **never** charged.

### Legality

Transcripts are publicly available caption data. Use this actor for content you have the right to process, and comply with YouTube's Terms of Service and applicable law. You are responsible for how you use the exported data.

### FAQ

**Do I need a YouTube API key?** No.
**Can it do Shorts?** Yes — pass the `/shorts/` URL or the ID.
**Which languages?** Whatever the video publishes; use `lang` to prefer one.
**Why did a video return an error?** Captions are disabled/unavailable, or the link was invalid — you were not charged.
**Can I get just plain text?** Use the `text` field; ignore `segments`.

### Support

Questions or a field you need added? Email **contact@endspec.net** — we typically reply within one business day.

# Actor input Schema

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

One or more YouTube video URLs or 11-character video IDs. Each video returns one transcript. Accepts watch?v=, youtu.be/, and /shorts/ links.

## `lang` (type: `string`):

Preferred transcript language as a 2-letter code (e.g. en, es, de). Leave blank for the video's default. If the requested language is unavailable the default is returned.

## Actor input object example

```json
{
  "videos": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ]
}
```

# Actor output Schema

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

// Run the Actor and wait for it to finish
const run = await client.actor("endspec/youtube-instant-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 = { "videos": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"] }

# Run the Actor and wait for it to finish
run = client.actor("endspec/youtube-instant-transcript-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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"
  ]
}' |
apify call endspec/youtube-instant-transcript-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=endspec/youtube-instant-transcript-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "YouTube Transcript Scraper – Video Captions & Subtitles by URL",
        "description": "Extract the full transcript of any YouTube video by URL or ID: timestamped caption segments plus clean, joined plain text. Batch many videos in one run. No login, no cookies, no YouTube API key. Pay only per transcript returned.",
        "version": "0.1",
        "x-build-id": "sNoh7db3TSQfyTOiu"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/endspec~youtube-instant-transcript-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-endspec-youtube-instant-transcript-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/endspec~youtube-instant-transcript-scraper/runs": {
            "post": {
                "operationId": "runs-sync-endspec-youtube-instant-transcript-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/endspec~youtube-instant-transcript-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-endspec-youtube-instant-transcript-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "videos"
                ],
                "properties": {
                    "videos": {
                        "title": "YouTube Videos",
                        "type": "array",
                        "description": "One or more YouTube video URLs or 11-character video IDs. Each video returns one transcript. Accepts watch?v=, youtu.be/, and /shorts/ links.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "lang": {
                        "title": "Language (optional)",
                        "type": "string",
                        "description": "Preferred transcript language as a 2-letter code (e.g. en, es, de). Leave blank for the video's default. If the requested language is unavailable the default is returned."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```