BulkTranscripts YouTube

Start a bulk extraction job

start_bulk_extract

Extract every transcript of a YouTube channel, playlist or video list in the background. Returns immediately with a run_id; the server discovers the videos (free), fetches each transcript into this account's library (1 credit per new transcript, cache hits and repeats free, failures never charged) and keeps going after this call returns. Transcripts it adds are free to read again from the library. Up to 1,000 videos per job, 2 jobs per account at a time; suited to anything larger than about 20 videos.

Input Schema

TableJSON Schema

Name	Required	Description
`url`	Yes	Channel (@handle or URL), playlist URL/id, or a single video URL.
`content`	No	For channels: which tab to read. Default 'videos' (long-form uploads); 'shorts' or 'live' for those tabs.
`language`	No	Preferred caption language code. Default 'en'.
`start_at`	No	1-based position to start from, newest first (default 1). For sources over 1,000 videos run blocks: start_at=1, then 1001, 2001…; the job status gives next_start_at when a block was full.
`max_videos`	No	Cap on videos to process, default 100.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No
`phase`	No
`quota`	No	Videos not attempted because credits ran out.
`total`	No
`cached`	No
`failed`	No
`run_id`	Yes
`source`	Yes
`status`	Yes	running, completed or stopped.
`billing`	Yes
`skipped`	No	Videos without captions; never charged.
`stopped`	No
`completed`	No
`remaining`	No
`interrupted`	No
`videos_found`	No	Null until a large channel has been listed.
`check_again_in_seconds`	Yes	Do not poll sooner than this.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 14, 2026

changedInput schema / properties / start_at / description

Previous value: -"1-based position to start from, newest first (default 1). For sources over 1,000 videos run blocks: start_at=1, then 1001, 2001…; get_bulk_status gives next_start_at when a block was full."New value: +"1-based position to start from, newest first (default 1). For sources over 1,000 videos run blocks: start_at=1, then 1001, 2001…; the job status gives next_start_at when a block was full."

Changed2 schema fields changedOct 13, 2026

addedInput schema / properties / content

Added value: +{
+  "description": "For channels: which tab to read. Default 'videos' (long-form uploads); 'shorts' or 'live' for those tabs.",
+  "enum": [
+    "videos",
+    "shorts",
+    "live"
+  ],
+  "type": "string"
+}

addedInput schema / properties / start_at

Added value: +{
+  "description": "1-based position to start from, newest first (default 1). For sources over 1,000 videos run blocks: start_at=1, then 1001, 2001…; get_bulk_status gives next_start_at when a block was full.",
+  "minimum": 1,
+  "type": "integer"
+}

Changed1 schema field changedSep 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "billing": {
+      "properties": {
+        "creditsCharged": {
+          "description": "Credits this call cost (0 on cache hits).",
+          "type": "integer"
+        },
+        "enabled": {
+          "type": "boolean"
+        },
+        "freeLimit": {
+          "type": "integer"
+        },
+        "granted": {
+          "type": "integer"
+        },
+        "kind": {
+          "description": "anon (free tier), license (paid) or admin.",
+          "type": "string"
+        },
+        "remaining": {
+          "description": "Credits left on this account.",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "unlimited": {
+          "type": "boolean"
+        },
+        "used": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "type": "object"
+    },
+    "cached": {
+      "type": "integer"
+    },
+    "check_again_in_seconds": {
+      "description": "Do not poll sooner than this.",
+      "type": "integer"
+    },
+    "completed": {
+      "type": "integer"
+    },
+    "error": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "failed": {
+      "type": "integer"
+    },
+    "interrupted": {
+      "type": "integer"
+    },
+    "phase": {
+      "type": "string"
+    },
+    "quota": {
+      "description": "Videos not attempted because credits ran out.",
+      "type": "integer"
+    },
+    "remaining": {
+      "type": "integer"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "skipped": {
+      "description": "Videos without captions; never charged.",
+      "type": "integer"
+    },
+    "source": {
+      "properties": {
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "url"
+      ],
+      "type": "object"
+    },
+    "status": {
+      "description": "running, completed or stopped.",
+      "type": "string"
+    },
+    "stopped": {
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "not_attempted": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "code"
+      ],
+      "type": "object"
+    },
+    "total": {
+      "type": "integer"
+    },
+    "videos_found": {
+      "description": "Null until a large channel has been listed.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "run_id",
+    "status",
+    "source",
+    "check_again_in_seconds",
+    "billing"
+  ],
+  "type": "object"
+}

AddedSep 18, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond the annotations: returns immediately with a run_id, keeps working after the call returns, discovery is free while fetching costs 1 credit per new transcript with cache hits and failures free, plus quotas of 1,000 videos per job and 2 concurrent jobs. None of this is inferable from the annotation set, which only flags it as non-read-only and open-world.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the async/run_id behavior, and each subsequent clause adds distinct information (billing, quotas, sizing). It is a dense single paragraph rather than cleanly separated points, which costs a little readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists so return-shape detail is unnecessary, and the description still explains the asynchronous lifecycle, cost model and job limits an agent needs before firing the call. Nothing required to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so url, content, language, start_at and max_videos are all documented in the schema itself, including the block-splitting convention. The description restates the 1,000-video cap but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (extract) plus resource (every transcript of a YouTube channel, playlist or video list) with the added qualifier that it runs in the background. This clearly differentiates it from synchronous siblings like get_transcript and get_transcripts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Suited to anything larger than about 20 videos" gives an explicit size-based criterion for when to prefer this over per-video extraction, and the pointer to job status for next_start_at hints at the follow-up sibling. It stops short of naming get_transcripts or get_bulk_status as alternatives by name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All BulkTranscripts YouTube tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?