# YouTube Transcript Scraper (`apihq/youtube-transcript-scraper`) Actor Extract timestamped YouTube transcripts as JSON segments. Single video or batch up to 50 IDs per run. Returns transcript + video metadata (title, channel, duration). Pay only for successful results, failed videos go to a separate errors dataset with machine-readable error codes. - **URL**: https://apify.com/apihq/youtube-transcript-scraper.md - **Developed by:** [apihq](https://apify.com/apihq) (community) - **Categories:** Videos, AI, Developer tools - **Stats:** 20 total users, 12 monthly users, 83.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 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. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Extract time-coded transcripts from any public YouTube video. No Google API key, no quota, no browser automation. Send one video ID or a batch of up to 50, get clean JSON segments with metadata back. Pay-per-result at $3 per 1,000 successful transcripts. Failed videos cost nothing. Designed for developers wiring transcripts into AI training data, search indexing, content analysis, accessibility tools, and moderation pipelines. ### Why this Actor Three properties competing transcript scrapers usually skip: 1. You pay only for successful extractions. Failed videos go to a separate dataset called `errors` and never trigger a charge. 2. Every failure carries a machine-readable code (`NO_CAPTIONS`, `PLAYABILITY`, `EMPTY_TRANSCRIPT`, `VALIDATION_FAILED`, `DEADLINE_EXCEEDED`) so your downstream pipeline can branch on the error type without parsing English text. 3. A 30-second deadline applies to every request. If the upstream is slow, you get a clean 504 and a refund, not a 60-minute hang that drains your budget. ### Who uses this - **AI engineers** feed transcripts into RAG pipelines so LLMs can answer questions about video content. - **Search teams** index spoken words to surface results that title-and-description search misses. - **Podcast and creator tools** pull quotes, generate chapters, and draft summaries from interview audio. - **Analytics and brand-safety teams** run sentiment, topic, and keyword extraction across thousands of videos. - **Accessibility and edtech builders** drop subtitle overlays into learning platforms and media players. - **Researchers** build NLP corpora from lectures, conference talks, and long-form interviews. ### Input example A single video with metadata included: ```json { "videoId": "jNQXAC9IVRw", "metadata": true } ```` A batch of three videos in a specific language: ```json { "videoIds": [ "jNQXAC9IVRw", "dQw4w9WgXcQ", "kJQP7kiw5Fk" ], "language": "en", "metadata": true } ``` The Actor caps batch input at 50 video IDs per run. For larger workloads, launch parallel runs. ### Output example A successful extraction in the default dataset (this is the actual response for "Me at the zoo", the first ever YouTube upload): ```json { "video_id": "jNQXAC9IVRw", "language": "en", "transcript": [ { "text": "All right, so here we are, in front of the elephants", "start": 1.2, "duration": 2.16 }, { "text": "the cool thing about these guys is that they have really really really long trunks", "start": 5.318, "duration": 7.298 }, { "text": "and that's pretty much all there is to say", "start": 16.881, "duration": 2 } ], "is_auto_generated": false, "available_tracks": [ { "language_code": "en", "language_name": "English", "is_auto_generated": false }, { "language_code": "de", "language_name": "German", "is_auto_generated": false } ], "metadata": { "title": "Me at the zoo", "author_name": "jawed", "author_url": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A", "thumbnail_url": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg", "channel_id": "UC4QobU6STFB0P71PMvOGN5A", "duration_seconds": 19 } } ``` A failed extraction lands in the `errors` dataset: ```json { "video_id": "00000000000", "code": "PLAYABILITY", "error": "Video 00000000000 is not playable: This video is unavailable", "request_id": "req_911f37d2e55644ff9d9e4a3f", "status_code": 403 } ``` You can quote the `request_id` when filing a support issue and we can trace the exact request in our logs. ### What you get For each successfully extracted video, one record lands in the default dataset with this shape: | Field | Type | What it is | |---|---|---| | `video_id` | string | The 11-character YouTube video ID. | | `language` | string | Language code of the selected caption track. | | `transcript` | array | Time-coded caption segments. Each has `text`, `start`, and `duration`. | | `is_auto_generated` | boolean | True if the selected track is YouTube's ASR. | | `available_tracks` | array | Every caption track the video exposes, with language code and name. | | `metadata` | object | Video title, channel name, channel URL, thumbnail URL, channel ID, duration in seconds. Present when `metadata: true` (default). | Failed videos do not pollute the default dataset. They go to a per-run dataset called `errors` with `video_id`, the machine-readable `code`, a human-readable `error` message, the backing service's `request_id` for support tickets, and the HTTP `status_code`. ### How to use this Actor 1. Open the Actor in the Apify Console. 2. Set `videoId` (single) or `videoIds` (up to 50 per run). Optionally pass `language` (e.g. `en`, `de`, `en-US`) and `metadata` (defaults to true). 3. Click Start. Successful transcripts land in the default dataset; failures land in a separate `errors` dataset. The Actor is also callable from the Apify API and every official integration (Make, Zapier, n8n, Slack, webhooks). The API tab in the Console has ready-to-paste JavaScript, Python, and curl snippets. ### Pricing Pay-per-result. Each successful transcript that lands in the default dataset costs `$0.003`, which works out to `$3.00 per 1,000 transcripts`. Failed videos cost nothing. Apify subscriber tier discounts apply automatically. Customers on the Scale plan pay roughly `$2.40 per 1,000`, and Business plan customers pay roughly `$1.80 per 1,000`. Platform compute is included in the per-event price. There is no separate compute bill or storage surprise. You can cap the maximum charge of a single run from Apify's Run Limits panel. The Actor honors that cap. If your budget runs out mid-batch, the run stops cleanly and reports how many items completed. ### Reliability Three guarantees worth knowing about before you wire this into a production pipeline: **Hard 30-second deadline per video.** If YouTube or the proxy network slows down, you get a `504` with `code: DEADLINE_EXCEEDED` for that video. You never wait minutes for a single result. **Empty transcripts are treated as failures.** If YouTube returns a caption track that parses to zero segments, the record goes to the `errors` dataset and is not billed. You never pay for a blank transcript. **Stable error taxonomy.** Every failure has a `code` your code can branch on. The codes are stable across releases. Common codes you might see: - `NO_CAPTIONS`: the video has no caption tracks at all. - `PLAYABILITY`: the video is unavailable, deleted, or geo-blocked. - `EMPTY_TRANSCRIPT`: tracks exist but parsed to zero usable segments. - `VALIDATION_FAILED`: the video ID format was wrong. - `DEADLINE_EXCEEDED`: the request hit the 30-second deadline. - `POTOKEN_REQUIRED`: YouTube has enabled PoToken enforcement for this track. Every error also carries a `request_id` that you can quote when filing a support issue. ### FAQ **Do I need a YouTube Data API key?** No. The Actor calls YouTube's public InnerTube endpoint directly and does not consume Google API quota. **Which videos work?** Public videos with caption tracks. Manual captions and auto-generated (ASR) captions both work. Private, age-gated, or members-only videos do not, since the Actor only reads public data. **What if a video has no captions?** The video goes to the `errors` dataset with `code: NO_CAPTIONS`. You are not charged. **Which languages are supported?** Every language the video creator uploaded. If you pass a `language` code (such as `en`, `de`, or `en-US`), the Actor picks the best matching track. If you omit `language`, the Actor prefers manual English first, then auto-generated English, then the first available track. **Can I scrape a whole channel or playlist?** Not with this Actor. This one takes single video IDs or short batches. A separate Actor for full channel and playlist transcript extraction is on the roadmap. Watch this Actor's changelog for updates. **Can I use this Actor from my own code?** Yes. Use the Apify API or one of the official SDKs (Node.js: `apify-client`, Python: `apify-client`). The Apify Console shows ready-to-paste code samples on the API tab. **Why do failures go to a separate dataset?** Apify's pay-per-event billing fires on writes to the default dataset. Putting failures in a named dataset means the Actor cannot accidentally bill you for a failure. You still see exactly what failed and why, with a `request_id` for support correlation. **What happens if YouTube rate-limits the request?** The request retries up to two times with exponential backoff. If it still cannot fetch the transcript within the 30-second deadline, the video goes to the `errors` dataset with `code: DEADLINE_EXCEEDED`. You are not charged. ### Roadmap These features are planned for future Actors in the same family: - Bulk channel transcript extractor: paste a channel URL, get every transcript in the channel. - Bulk playlist transcript extractor: paste a playlist URL, get every transcript on the playlist. - Single-video metadata Actor: title, channel, duration, and thumbnail only, priced cheaper than the full transcript. - Caption track listing Actor: list available tracks without downloading them, useful for filtering before bulk runs. Each will be a separate Actor, listed under the same publisher. ### Found a bug or want a feature? Open an issue on this Actor's Issues tab and include the `request_id` from any error record you saw. We respond within one business day. # Actor input Schema ## `videoId` (type: `string`): 11-character YouTube video ID. Use this for a single transcript. ## `videoIds` (type: `array`): Array of 11-character YouTube video IDs. ## `language` (type: `string`): ISO 639-1 language code, optionally with region (e.g. 'en', 'en-US', 'de'). If omitted, picks manual English first, then auto-generated English, then the first available track. ## `metadata` (type: `boolean`): If true (default), include title, author, duration, and thumbnail in each transcript record. ## Actor input object example ```json { "videoId": "jNQXAC9IVRw", "metadata": true } ``` # Actor output Schema ## `transcripts` (type: `string`): One record per successfully fetched 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "videoId": "jNQXAC9IVRw" }; // Run the Actor and wait for it to finish const run = await client.actor("apihq/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "videoId": "jNQXAC9IVRw" } # Run the Actor and wait for it to finish run = client.actor("apihq/youtube-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 '{ "videoId": "jNQXAC9IVRw" }' | apify call apihq/youtube-transcript-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apihq/youtube-transcript-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Transcript Scraper", "description": "Extract timestamped YouTube transcripts as JSON segments. Single video or batch up to 50 IDs per run. Returns transcript + video metadata (title, channel, duration). Pay only for successful results, failed videos go to a separate errors dataset with machine-readable error codes.", "version": "0.1", "x-build-id": "RUn2KDzKjaTPFW1lg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apihq~youtube-transcript-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apihq-youtube-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/apihq~youtube-transcript-scraper/runs": { "post": { "operationId": "runs-sync-apihq-youtube-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/apihq~youtube-transcript-scraper/run-sync": { "post": { "operationId": "run-sync-apihq-youtube-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", "properties": { "videoId": { "title": "Single video ID", "pattern": "^[A-Za-z0-9_-]{11}$", "type": "string", "description": "11-character YouTube video ID. Use this for a single transcript." }, "videoIds": { "title": "Multiple video IDs", "maxItems": 50, "type": "array", "description": "Array of 11-character YouTube video IDs.", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" } }, "language": { "title": "Preferred language", "type": "string", "description": "ISO 639-1 language code, optionally with region (e.g. 'en', 'en-US', 'de'). If omitted, picks manual English first, then auto-generated English, then the first available track." }, "metadata": { "title": "Include video metadata", "type": "boolean", "description": "If true (default), include title, author, duration, and thumbnail in each transcript record.", "default": true } } }, "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 } } } } } } } } } } ```