The YouTube transcript API, ready for code.

ids accepts video IDs or full YouTube URLs. Optional lang sets the preferred caption language and falls back to whatever the video has.

Need generated types or every nested field? Use the exhaustive OpenAPI schema.

curl -X POST https://vidwords.com/api/transcripts \
  -H "Authorization: Basic YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["dQw4w9WgXcQ", "https://youtu.be/jNQXAC9IVRw"], "lang": "en"}'

const res = await fetch("https://vidwords.com/api/transcripts", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw"], lang: "en" }),
});
const data = await res.json();
console.log(data.results);

import requests

res = requests.post(
    "https://vidwords.com/api/transcripts",
    headers={
        "Authorization": "Basic YOUR_API_TOKEN",
        "Content-Type": "application/json",
    },
    json={"ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw"], "lang": "en"},
)
print(res.json()["results"])

Transcript provenance: the optional source field describes the text as captions, auto_captions, transcribed or browser_capture. Use it instead of the legacy method marker. Provider details and internal quality measurements are not part of the customer response.

Compatibility update · October 17, 2026: existing audio and browser method markers remain available for installed clients; caption retrieval methods are grouped together. New integrations should use source.

Response:

{
  "results": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "…",
      "author": "…",
      "language": "English",
      "languageCode": "en",
      "isGenerated": false,
      "text": "full transcript as one string…",
      "segments": [{ "text": "…", "start": 1.36, "duration": 1.68 }, …]
    },
    { "id": "…", "error": "no_transcript", "message": "No transcript is available for this video" }
  ],
  "cloudRequestsRemaining": 123,
  "aiUnitsRemaining": 580
}

Available on Starter (up to 10 channels/request), Pro (100), and Team (500). ids accepts @handles, channel URLs, or UC… channel IDs. Each successful channel listing uses one Cloud Request; retrieving transcripts uses one more per delivered video.

Need generated types or every nested field? Use the exhaustive OpenAPI schema.

curl -X POST https://vidwords.com/api/channels \
  -H "Authorization: Basic YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["@mkbhd"]}'

const res = await fetch("https://vidwords.com/api/channels", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ids: ["@mkbhd"] }),
});
console.log((await res.json()).results);

import requests

res = requests.post(
    "https://vidwords.com/api/channels",
    headers={"Authorization": "Basic YOUR_API_TOKEN", "Content-Type": "application/json"},
    json={"ids": ["@mkbhd"]},
)
print(res.json()["results"])

Response:

{
  "results": [
    {
      "id": "@mkbhd",
      "channelId": "UCBJycsmduvYEL83R_U4JriQ",
      "title": "…",
      "videoCount": 500,
      "truncated": true,
      "videos": [{ "id": "…", "title": "…", "author": "…" }, …]
    }
  ]
}

Everything above reads captions. This reads the picture — slides, charts, demos, on-screen text a transcript never contains — and returns evidence tied to exact timestamps.

The part worth paying for is what it refuses to say. Every citation is checked against the stored analysis before you see it: a visual claim must match a real recorded frame, a spoken one a real transcript segment. When nothing survives the check, the answer says the evidence is insufficient instead of guessing.

Analysis takes minutes, so this is asynchronous — start a job, then poll it. Standard Watch uses 4 AI Processing Units per minute of video; Deep Watch uses 30.

Start an analysis

curl -X POST https://vidwords.com/api/watch \
  -H "Authorization: Basic YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "dQw4w9WgXcQ", "mode": "smart"}'

# -> 202 {"jobId": 1234, "status": "queued", ...}
# (this account already ran the same analysis — same video, mode and range?
#  then you get that job back free: 200 if it is ready, 202 while it still runs)
# (already analysed for someone else? -> 200 {"status": "ready", "cached": true, ...}
#  at once, and no watch.completed webhook follows: read the result from this response)

const auth = { "Authorization": "Basic YOUR_API_TOKEN" };

const start = await fetch("https://vidwords.com/api/watch", {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ id: "dQw4w9WgXcQ", mode: "smart" }),
});
// Check this. A refusal (402 out of minutes, 422 too long, 503 unavailable)
// returns {error, message} and no jobId — polling it would just 404 forever.
if (!start.ok) {
  const { error, message } = await start.json();
  throw new Error(`${error}: ${message}`);
}
const { jobId } = await start.json();

// Poll until ready — usually a few minutes.
let job;
do {
  await new Promise((r) => setTimeout(r, 10_000));
  job = await (await fetch(`https://vidwords.com/api/watch/${jobId}`, { headers: auth })).json();
} while (job.status === "queued" || job.status === "processing");

if (job.status === "failed") throw new Error(job.error ?? "analysis failed");
console.log(job.artifact);

GET/api/watch/:jobId

Poll this until status is ready, then read artifact — the summary, chapters and timestamped evidence. Analyses from October 2026 also carry brief (the TL;DR, each bullet with the second that supports it), facts (every figure the video states, verbatim, with where it is stated), videoKind and followUps; older ones carry keyPoints instead. Treat every one of those as optional. While queued or processing there is no artifact yet. A failed job carries errorCode and retryable. Free.

POST/api/watch/:jobId/ask

Ask a question against a finished analysis. Returns the answer with its verified citations, or says the evidence is insufficient. Uses 6 AI Processing Units.

curl -X POST https://vidwords.com/api/watch/1234/ask \
  -H "Authorization: Basic YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "What database did they benchmark against?"}'

Good to know

• Starting the same analysis twice does not charge twice. A run of the same video, mode and range already queued, running or finished on your account comes back as that same job.
• Standard Watch uses 4 AI Processing Units per minute of video; Deep Watch uses 30. Free includes 200 AI Units/month, Starter 3,000, Pro 10,000 and Team 28,000, followed by any purchased AI top-up balance.
• A run refused before it starts — video not public, age-restricted, too long, out of minutes — costs nothing.
• Start is limited to 10 requests/minute and polling to 30 per 10 seconds, so a polling loop can’t lock you out of starting the next job.
• Agents can reach all of this through the MCP server as analyze_video, get_analysis and ask_video.

Point Claude, ChatGPT, Cursor, or any MCP-compatible agent at https://vidwords.com/mcp and it can read and search YouTube videos on its own — same API token, same Cloud and AI balances, no glue code to write.

The tool worth knowing about is search_transcript. It returns the moments matching your question with timestamps and youtube.com/watch?v=…&t=…s links already attached, so the assistant answers with a citation you can click instead of pasting the whole transcript at you.

Connect it

claude mcp add --transport http vidwords https://vidwords.com/mcp \
  --header "Authorization: Basic YOUR_API_TOKEN"

// claude_desktop_config.json — Desktop runs only local servers, so
// bridge the remote one with mcp-remote (or add it under Customize →
// Connectors, which signs in with no key at all). The key goes in env:
// Claude Desktop on Windows does not escape spaces inside args.
{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
               "--header", "Authorization:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

# .cursor/mcp.json
{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp",
      "headers": { "Authorization": "Basic YOUR_API_TOKEN" }
    }
  }
}

Tools

Re-reading a video you already have is free — another time range, another page, or a search after a fetch — and every metered result reports what it charged.

Good to know

• Prefer search_transcript over get_transcript. Both cost the same, but a full transcript of a two-hour video fills the assistant's context with material irrelevant to your question. Search returns only the parts that answer it.
• Ask for a time span instead of a whole video. Both transcript tools take optional from and to timecodes — seconds (615), m:ss (10:20) or h:mm:ss (1:02:13). It's the same format the tools print back, so a timestamp from one answer can be pasted straight into the next question.
• The MCP endpoint uses the same plan-based request limit as REST: 60 requests/minute on Free, 200 on Starter, 500 on Pro, and 1,000 on Team. Starting an analysis has its own 10 requests/minute safety limit.
• Cloud and AI balances work exactly as they do over REST: one Cloud Request per delivered transcript, AI Units for analysis, nothing for a failed lookup, and a readable error before a job exceeds its balance.
• Ran out mid-conversation? The assistant gets a readable error telling it to check account or top up, rather than an opaque failure it will just retry.
• Clients that support MCP sign-in need no token at all; anything headless sends a VidWords API key (Basic), created on the API & MCP page. RapidAPI keys don't work here.

Add an HTTPS endpoint on the API & MCP page and VidWords sends it a signed POST for every event below. Pro allows 5 endpoints and Team 20. The endpoint must be a public https:// URL on port 443. Its signing secret (whsec_…) is shown once, when you create it.

Every delivery has the same envelope:

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: VidWords-Webhooks/1.0
X-VidWords-Event: watch.completed
X-VidWords-Delivery: evt_3f9c1a7b2d4e6f80a1b2c3d4e5f60718
X-VidWords-Signature: t=1760261400,v1=5d41402abc4b2a76b9719d911017c592ae2f5c1c6e2b8d1b5f4a3c2e1d0f9a8b

{
  "id": "evt_3f9c1a7b2d4e6f80a1b2c3d4e5f60718",
  "type": "watch.completed",
  "createdAt": "2026-10-12T09:30:00.000Z",
  "data": { "jobId": 1234, "videoId": "dQw4w9WgXcQ", "mode": "smart", "origin": "user", "status": "ready" }
}

Verify the signature

X-VidWords-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw request body>" keyed with your endpoint’s signing secret. Compute it over the body exactly as it arrived, before any JSON parsing, and compare in constant time.

import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.VIDWORDS_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300; // refuse anything signed more than 5 minutes away

function verify(rawBody, header) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((pair) => pair.trim().split("="))
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));
}

const seen = new Set(); // use your database in production

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const raw = Buffer.concat(chunks).toString("utf8");
    if (!verify(raw, req.headers["x-vidwords-signature"])) {
      res.writeHead(400).end();
      return;
    }
    res.writeHead(204).end(); // acknowledge first, then do the work
    const event = JSON.parse(raw);
    if (seen.has(event.id)) return; // a retry of an event you already handled
    seen.add(event.id);
    console.log(event.type, event.data);
  });
}).listen(8080);

Retries and replays

• Answer with any 2xx within 10 seconds. Anything else counts as a failure: another status, a timeout, or a redirect, which is not followed.
• Failed deliveries are retried 10 seconds, 1 minute, 5 minutes and 30 minutes after each failed attempt, so five attempts in all over about 36 minutes. After the fifth, the delivery is marked failed.
• Delivery is at least once and unordered. A retry carries the same id and X-VidWords-Delivery, so de-duplicate on it.
• Refuse stale signatures. Each attempt is signed afresh with the current time, so a 5-minute tolerance on t rejects a captured request replayed later without ever rejecting a genuine retry.
• Pausing an endpoint stops new events reaching it. If your plan stops including webhooks, pending deliveries are stopped too.

Every event’s schema is in the webhooks section of the OpenAPI specification.