API Documentation

Two ways to get YouTube transcripts: pull on your schedule, or receive them by webhook shortly after a new video drops.

Authentication

The Pull API uses API key authentication. Create a key under Connect & API keys in the dashboard. Pass it using any of these methods:

Recommended
Authorization: Bearer tr_live_xxxxxxxxxxxx
X-Api-Key: tr_live_xxxxxxxxxxxx
GET /api/videos?api_key=tr_live_xxxxxxxxxxxx

Webhooks don't require authentication — you configure the endpoint URL when creating a subscription. TranscriptHook will POST to that URL whenever a new video is detected.

Pull API

Fetch all transcripts detected for your subscriptions within a time window. Good for batch processing, scheduled jobs, or polling-based integrations.

GET /api/videos

Query Parameters

Parameter Type Default Description
since string 24h Time window. Accepts Nh (hours) or Nd (days). Examples: 6h, 7d.
tag string — Filter by subscription label. If omitted, returns videos from all subscriptions.

Example Request

curl https://transcripthook.com/api/videos?since=24h&tag=my-channel \
  -H "Authorization: Bearer tr_live_xxxxxxxxxxxx"

Response

{
  "videos": [
    {
      "id": 1234,
      "subscription_id": 42,
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_name": "HomeBrewers",
      "tag": "my-channel",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "How to Brew a West Coast IPA",
      "description": "Full recipe and gear list below.\nKit: https://example.com/kit\n0:00 Intro",
      "published_at": "2026-04-30T10:00:00.000Z",
      "transcript_available": true,
      "transcript_text": "Welcome to today's brew session...",
      "transcript_source": "proxy",
      "detected_at": "2026-04-30T10:05:12.000Z",
      "ai_summary": null,
      "ai_key_takeaways": null,
      "ai_topics": null
    }
  ],
  "query": {
    "tag": "my-channel",
    "since": "24h",
    "cutoff": "2026-04-29T10:05:12.000Z"
  }
}

Response Fields

Field Type Description
video_id string YouTube video ID. Construct the full URL as https://www.youtube.com/watch?v={video_id}. Use this for deduplication.
channel_id string YouTube channel ID (e.g. UCxxxxxx).
channel_name string Channel display name, as shown on YouTube.
tag string | null The label you set on the subscription. Useful for routing videos to different pipelines.
video_title string Video title at time of detection.
description string | null The full YouTube video description, which often contains links (GitHub repos, sponsors, chapters). null for videos stored before descriptions were captured, or when YouTube did not return one.
published_at ISO 8601 When the video was published on YouTube.
transcript_available boolean false only when YouTube explicitly reports transcripts are disabled for this video.
transcript_text string | null Full transcript as plain text. null if unavailable.
transcript_source string proxy, direct, or scraperapi — which fetch method succeeded.
detected_at ISO 8601 When TranscriptHook first detected this video.
ai_summary string | null AI-generated 2–3 sentence summary of the video. Pro and Agency plans only (coming soon).
ai_key_takeaways string[] | null Array of key takeaways extracted from the transcript. Pro and Agency plans only (coming soon).
ai_topics string[] | null Array of topic tags for the video. Pro and Agency plans only (coming soon).
subscription_id integer Internal subscription ID. Stable identifier for the channel subscription that triggered this.

On-Demand Transcript

Fetch the transcript for any YouTube video by URL or video ID — no channel subscription required. Each successful fetch counts against your monthly lookup quota. Failed fetches (transcript unavailable) are free.

GET /api/transcript

Query Parameters

ParameterTypeDescription
url string Full YouTube URL (e.g. https://youtube.com/watch?v=abc123 or https://youtu.be/abc123). Use either url or video_id, not both.
video_id string YouTube video ID (11-character string, e.g. dQw4w9WgXcQ).
format string Optional. json (default), srt, vtt or md. The last three return the transcript as a plain-text body (text/vtt for vtt) instead of JSON. Credits work the same: one credit per successful fetch. If no transcript is available you still get the JSON response with available: false, at no charge.

Example Request

curl "https://transcripthook.com/api/transcript?video_id=dQw4w9WgXcQ" \
  -H "Authorization: Bearer tr_live_xxxxxxxxxxxx"

Response

{
  "video_id": "dQw4w9WgXcQ",
  "available": true,
  "text": "Full transcript as plain text...",
  "segments": [
    { "start": 0, "duration": 4, "text": "Never gonna give you up" },
    ...
  ],
  "description": "Full YouTube description, including any links...",
  "credits_remaining": 2499
}

Response Headers

HeaderDescription
X-Credits-Remaining Lookups remaining this month. Agency starts at 10,000 (no plan is unlimited).

Error Responses

StatusErrorMeaning
400 url or video_id is required Neither parameter was provided, or the URL couldn't be parsed.
400 format must be one of json, srt, vtt, md Unsupported format value. No credit is used.
402 credits_exhausted Monthly lookup quota reached. Resets on the 1st of each month.

Monthly quotas

PlanLookups / month
Free10
Starter500
Pro2,500
Agency10,000

MCP — Claude & Cursor Integration

TranscriptHook ships a Model Context Protocol server at https://transcripthook.com/mcp. Connect it from Claude Code, Claude Desktop, claude.ai, ChatGPT, VS Code or Cursor with one browser approval, or add it to any other MCP-compatible client with an API key. Your AI assistant can read your channel data, pull transcripts, check what's left on your plan, and manage which channels you monitor — no copy-pasting, no API calls to write.

Connect your AI assistant

Pick your client. Each one connects through your browser: log in to TranscriptHook, check what the app is asking for, and approve. No API key to copy.

Claude Code

claude mcp add --transport http transcripthook https://transcripthook.com/mcp

Then run /mcp in Claude Code and choose Authenticate. Your browser opens; log in and approve. After that, paste any YouTube link and ask for what you need: "Get the transcript for https://youtu.be/… and summarize the key points."

Claude.ai & Desktop

Add to Claude

If the form doesn't open pre-filled: Settings → Connectors → Add custom connector, name it TranscriptHook and paste https://transcripthook.com/mcp. Claude Desktop uses the same connectors as your claude.ai account.

ChatGPT

In ChatGPT, open Settings → Apps & Connectors, turn on Developer mode under Advanced, then create a connector with this URL and OAuth authentication: https://transcripthook.com/mcp

VS Code

Install in VS Code VS Code Insiders

VS Code opens, adds the server, and asks you to sign in to TranscriptHook in your browser.

Cursor

Add to Cursor

Cursor desktop signs in through your browser. If sign-in fails (older Cursor versions or Cloud Agents), use the API key method under Other clients.

Apps connected through the browser can read your data and add, pause or resume channels. Removing channels is never granted to them. Manage them under Connected apps in Dashboard → Connect & API keys.

The approval screen names the app asking for access (the name is supplied by the app, not verified by us), shows the account you are signed in as, lists what it can and cannot do, and states which address you will be sent to afterwards. Check that address before you approve.

Revoking access. Connected apps are listed in Dashboard → Connect & API keys under Connected apps. Revoke cuts the app off immediately. Apps connected this way can read your data and add, pause or resume channels, within your plan limits. remove_channel is never granted through OAuth.

Other clients

For clients without OAuth support, scripts, or Cursor versions where browser sign-in fails, send your API key as a header. Add the following to your MCP client config; for Cursor it's in Settings → MCP.

{
  "mcpServers": {
    "transcripthook": {
      "url": "https://transcripthook.com/mcp",
      "headers": {
        "Authorization": "Bearer tr_live_xxxxxxxxxxxx"
      }
    }
  }
}

Create an API key in Dashboard → Connect & API keys. The MCP server accepts the same keys as the REST API.

Claude Code with a key instead of OAuth:

claude mcp add --transport http --scope user transcripthook https://transcripthook.com/mcp \
  --header "Authorization: Bearer tr_live_xxxxxxxxxxxx"

The Other clients / API key section of the Connect your AI assistant card in Dashboard → Connect & API keys fills in the key for you right after you create one under API keys (while the one-time dialog is open). Creating a key does not affect your other keys; revoke a key there to cut off a single client. Run claude mcp list or /mcp to check the connection.

Available Tools

ToolDescriptionCredits
get_transcript Fetch the full transcript for any YouTube video by ID or URL 1 per successful fetch
get_recent_videos Get videos from your monitored channels within a time window (e.g. since: "24h"), including full transcripts Free
search_videos Search your subscription history by keyword — matches video titles and transcript text Free
list_channels List your monitored channels with latest video info. Each row includes a subscription_id that the tools below accept Free
get_account_status Your plan and everything metered against it — channels used vs. allowed, webhooks, remaining transcript credits and their reset date, rate limit, poll interval. Unlimited values come back as null Free
add_channel Start monitoring a channel by @handle, URL or UC… ID. Already monitoring it? You get the existing subscription back rather than a duplicate. Counts against your plan's channel limit Free
set_channel_active Pause or resume a channel. Paused channels are skipped by the poller but keep every stored video and transcript. A paused channel still occupies a slot against your channel limit Free
remove_channel Permanently delete a channel and all stored videos, transcripts and delivery records for it. Requires an explicit confirm: true, and is disabled unless you enable destructive tools for the key — see below Free

Three of these tools write to your account — they add, pause and delete subscriptions using the same plan limits as the dashboard. An OAuth connection or an API key is what authorises them. Treat your API key like a password: anyone holding it can change what you monitor. OAuth connections can be revoked in Connected apps. Revoke a key any time in Dashboard → Connect & API keys. Webhook URLs are deliberately not settable over MCP — configure those in the dashboard.

remove_channel is disabled by default. Until you enable destructive tools in Dashboard → Settings (an account setting that applies to your API keys, never to browser-approved apps), the tool is not advertised to your assistant at all and is refused if called — every other tool works normally. It changes only when you toggle it.

Why it works this way: the confirm: true flag is a speed bump for a well-behaved assistant, not a security boundary, because the model decides whether to set it. Transcripts are written by the channel owner, not by you, so a video whose captions contain instructions aimed at your assistant is a real possibility once that assistant can also delete things. The dashboard toggle is the part of the gate that no text your assistant reads can flip. Deletion is irreversible and we keep no per-account backup of transcripts.

Example prompts

  • "Summarize everything my channels posted in the last 24 hours."
  • "Search my channels for any video mentioning 'interest rates' this week."
  • "Fetch the transcript for youtube.com/watch?v=abc123 and pull out the key points."
  • "Which of my channels posted the most content last month?"
  • "How many transcript credits do I have left this month?"
  • "Start monitoring @Bloomberg and tag it finance."
  • "Pause the channels I haven't gotten a video from in 60 days."

Webhooks

Configure a webhook URL on any subscription and TranscriptHook will POST a JSON payload to it within minutes of a new video being published. No polling required.

Request Headers

HeaderValue
Content-Type application/json
User-Agent VidProxy/1.0
X-VidProxy-Event new_video (or test for a dashboard test send)
X-VidProxy-Delivery-Id A UUID for this delivery. The same value on every retry of it, so you can dedupe on it.
X-VidProxy-Timestamp Unix time in seconds when this attempt was sent. New on every attempt.
X-VidProxy-Signature v1= + hex HMAC-SHA256 of the timestamp, a dot and the raw body. See Verifying webhook signatures.

Payload

{
  "event": "new_video",
  "timestamp": "2026-04-30T10:05:12.000Z",
  "subscription": {
    "id": 42,
    "label": "my-channel",
    "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
    "channel_name": "HomeBrewers"
  },
  "video": {
    "id": "dQw4w9WgXcQ",
    "title": "How to Brew a West Coast IPA",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "published": "2026-04-30T10:00:00.000Z",
    "description": "Full recipe and gear list below.\nKit: https://example.com/kit\n0:00 Intro"
  },
  "transcript": {
    "available": true,
    "text": "Welcome to today's brew session...",
    "segments": [
      { "text": "Welcome to today's brew session", "start": 0.5, "duration": 3.2 }
    ]
  },
  "enrichment": {
    "summary": "A step-by-step guide to brewing a West Coast IPA...",
    "key_takeaways": ["Use high-alpha hops for bittering", "Dry hop at 68°F for best aroma", "Cold crash before packaging"],
    "topics": ["IPA", "hops", "dry hopping", "homebrewing"]
  },
  "matched_keywords": ["west coast"],
  "keyword_matches": [
    {
      "keyword": "west coast",
      "in_title": true,
      "occurrences": 4,
      "snippets": [
        {
          "text": "… the classic West Coast style leans on Cascade and Centennial …",
          "start_seconds": 412,
          "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=412s"
        }
      ]
    }
  ]
}

The enrichment field is only present on Pro and Agency plans (coming soon) with AI enrichment enabled. transcript.segments contains per-segment timing data when available.

video.description is the full YouTube description (often containing links), or null when unknown. It is informational: keyword filters match the title and transcript only, not the description.

matched_keywords is always present: [] when the subscription has no keyword filter, otherwise the keywords that matched this video, spelled as you typed them. keyword_matches appears only alongside a match and says where each keyword hit (in_title, occurrences) with up to three short snippets you can quote. start_seconds and the timestamped url are null when the transcript has no timing data.

A test send from the dashboard uses this same shape, but with "event": "test" and "test": true at the top level and placeholder video data — branch on event if you need to distinguish or ignore it.

Verifying webhook signatures

Every webhook, including retries and dashboard test sends, is signed with your account's signing secret. Find it under Dashboard → Settings → Webhook signing. It starts with whsec_, and you use the whole string, prefix included, as the HMAC key.

Verifying is optional. The signature headers are extra headers on the same request. If your receiver ignores them it keeps working exactly as before, and nothing has to change on your side.

To verify a request:

  1. Read the raw request body, the exact bytes received, before any JSON parsing. A parsed-and-re-serialised body can differ by a single byte and fail the check.
  2. Reject the request if X-VidProxy-Timestamp is more than 5 minutes away from your clock. That stops an old captured request being replayed.
  3. Compute v1= + hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with your secret.
  4. Compare it with X-VidProxy-Signature using a constant-time comparison.

Each retry carries a new timestamp and a new signature, so a retry that arrives hours later still passes the 5-minute check.

Node.js (Express)

const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = process.env.TRANSCRIPTHOOK_WEBHOOK_SECRET; // whsec_…

// express.raw() keeps the exact bytes. express.json() would give you a re-parsed object.
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-VidProxy-Timestamp') || '';
  const sig = req.get('X-VidProxy-Signature') || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(400).send('stale or missing timestamp');
  }
  const expected = 'v1=' + crypto.createHmac('sha256', SECRET)
    .update(ts + '.').update(req.body).digest('hex');
  const ok = sig.split(',').some(s => {
    const a = Buffer.from(s.trim()), b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // Dedupe on req.get('X-VidProxy-Delivery-Id'), then process event…
  res.sendStatus(200);
});

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, abort, request

SECRET = os.environ["TRANSCRIPTHOOK_WEBHOOK_SECRET"].encode()  # whsec_…
app = Flask(__name__)

@app.post("/hook")
def hook():
    raw = request.get_data()  # exact bytes, before any JSON parsing
    ts = request.headers.get("X-VidProxy-Timestamp", "")
    sig = request.headers.get("X-VidProxy-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(400)
    expected = "v1=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not any(hmac.compare_digest(s.strip(), expected) for s in sig.split(",")):
        abort(401)
    event = request.get_json()
    # Dedupe on request.headers["X-VidProxy-Delivery-Id"], then process event…
    return "", 200

n8n (Code node): in the Webhook node, open Options and turn on Raw Body, so the exact bytes arrive as binary data. Then add a Code node (Run Once for All Items) straight after it. On self-hosted n8n the crypto module has to be allowed with NODE_FUNCTION_ALLOW_BUILTIN=crypto.

const crypto = require('crypto');
const SECRET = 'whsec_…'; // better: keep it in an n8n variable or environment variable

const headers = $input.first().json.headers;
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // exact bytes received
const ts = headers['x-vidproxy-timestamp'] || '';
const sig = headers['x-vidproxy-signature'] || '';

if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
  throw new Error('Stale or missing webhook timestamp');
}
const expected = 'v1=' + crypto.createHmac('sha256', SECRET)
  .update(ts + '.').update(raw).digest('hex');
const ok = sig.split(',').some(s => {
  const a = Buffer.from(s.trim()), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
});
if (!ok) throw new Error('Bad webhook signature');

// Downstream nodes get the payload at $json (not $json.body), e.g. $json.transcript.text
return [{ json: { ...JSON.parse(raw.toString('utf8')), delivery_id: headers['x-vidproxy-delivery-id'] } }];

Regenerating the secret in the dashboard invalidates the old one immediately, for every subscription and for deliveries already waiting to be retried. Update your receivers right after you regenerate.

Retries

If your endpoint returns a non-2xx status, doesn't answer within 10 seconds, or can't be reached, TranscriptHook retries straight away, up to 3 times:

1 Retry after 2 seconds
2 Retry after 10 seconds
3 Retry after 30 seconds

If all of those fail, the delivery is kept and retried up to 5 more times, each one this long after the previous attempt:

4 About 10 minutes
5 About 30 minutes
6 About 2 hours
7 About 6 hours
8 About 16 hours

That covers roughly 25 hours from the first failure. After the last retry the delivery is marked failed for good. These later retries run on our polling cycle, which runs every 10 minutes, so each can fire up to one cycle late. We work through at most 10 retries per cycle, and an endpoint that fails isn't tried again in the same cycle.

Every retry sends the same body and the same X-VidProxy-Delivery-Id, with a new timestamp and signature. Retries go to the subscription's current webhook URL, so if you fix a broken URL, the next retry uses it.

We stop retrying early, and the delivery stays failed, when:

  • your endpoint answers 410 Gone;
  • the URL fails our safety check because its hostname doesn't resolve or resolves to a private or internal address (we check again before every attempt);
  • you pause the subscription or remove its webhook URL.

Other 4xx responses are retried, because they're often fixed on your side. An inactive n8n workflow answering 404 is a common example. The Delivery Log shows when a retry is scheduled and when retrying stopped. Make your endpoint idempotent: dedupe on X-VidProxy-Delivery-Id, or on subscription.id plus video.id.

Responding to Webhooks

Return any 2xx status code within 10 seconds. If your processing takes longer, acknowledge immediately and handle async.

Testing Your Webhook

You don't need to wait for a real video to find out if your endpoint is set up correctly. Open the subscription's Edit modal in the dashboard and click Send test to fire a synthetic payload at your webhook URL immediately, including one you haven't saved yet, and see a pass/fail result right away. Test sends go through the same SSRF-guarded delivery path as a real webhook and are signed with your real secret, so they're also the way to check your signature verification. They're a single attempt with no retry and aren't written to the Delivery Log. Once your subscription is live, a failed delivery also shows up as a badge directly on the subscription card in the dashboard, so you no longer have to open the Delivery Log to notice a broken endpoint.

Keyword Alerts

Keyword Alerts let you save keywords and receive an email whenever any new video across all your subscriptions mentions them — matched against the video title and transcript. This is separate from per-subscription keyword filters, which control webhook delivery.

Managing alerts

Alerts are managed from the Keyword Alerts tab in your dashboard. Add a keyword, and TranscriptHook will email you each time a new video matches it. Up to 50 keywords per account.

Match behavior

  • Case-insensitive, whole-word match — gpt matches "GPT-4" and "GPT is…" but not "ChatGPT", and fed matches "the Fed's decision" but not "federal". Phrases work (federal reserve). There is no stemming: tariff does not match "tariffs", so add both.
  • Matches run against both the video title and the full transcript text.
  • If a transcript is not yet available, the title is checked immediately; the transcript is checked once it becomes available.
  • If multiple keywords match the same video, you receive one email listing all matched keywords.

Per-subscription keyword filter

Subscriptions also support a per-subscription Keyword Filter (set in the subscription edit modal, comma-separated, up to 25 keywords). This controls webhook delivery only — the webhook fires only when the video title or full transcript matches one of the keywords, using the same whole-word rules as above, and the payload says which ones (matched_keywords). It does not send emails and is independent of Keyword Alerts.

  • A video that does not match is stored (readable through the Pull API) but not delivered; the Delivery Log records it as filtered · no keyword match.
  • With a filter set, a video is held until its transcript is available, even if Wait for transcript is off — the filter has nothing to match against otherwise. If no transcript arrives within 24 hours it is skipped, never delivered unchecked, and logged as skipped · no transcript to match.
  • Available on every plan, including Free. If a plan ever stops including filters, a filter left on it pauses that subscription's webhook (paused · filter not in your plan) until you clear it; clearing always works.

API

MethodEndpointDescription
GET/api/keyword-alertsList all keyword alerts
POST/api/keyword-alertsCreate a keyword alert — body: { "keyword": "string" }
DELETE/api/keyword-alerts/:idDelete a keyword alert

Rate Limits

The Pull API is rate-limited per API key against two windows checked together: a burst limit (sliding 60 seconds) and a sustained limit (sliding 24 hours). A request has to fit under both. Response headers tell you your current usage:

HeaderDescription
X-RateLimit-Limit Max burst requests per minute for your plan.
X-RateLimit-Remaining Requests remaining in the current minute window.
X-RateLimit-Limit-Day Max requests per day for your plan.
X-RateLimit-Remaining-Day Requests remaining in the current day window.
Retry-After Seconds until the window that refused the request resets (only on 429 responses).

When you exceed either limit you receive a 429 Too Many Requests with a Retry-After header and a limit_type field (burst or daily) in the JSON body naming which one you hit. Back off and retry after that delay.

Plans

Plan Channels Webhooks API req / min API req / day Transcript lookups / mo
Free 1 1 15 100 10
Starter 15 3 20 300 500
Pro 100 Unlimited 60 3,000 2,500
Agency 1,000 Unlimited 100 8,000 10,000

View pricing →

FAQ

How do I authenticate a request?
Send your API key in whichever form suits the client: an Authorization: Bearer header, an X-Api-Key header, or an api_key query parameter. Create keys in Dashboard → Connect & API keys. You can have several named keys and revoke one without affecting the others. Keys are stored hashed, so the full key is shown only once, when you create it — if you lose it, create a new one and revoke the old.
Pull API or webhooks — which should I use?
Webhooks push: TranscriptHook POSTs to your URL within minutes of a new video, so nothing on your side runs on a timer. The pull API covers the cases a push doesn't fit — batch jobs, backfilling after an outage, or any environment with no public URL to POST to. GET /api/videos?since=24h returns everything detected in that window with transcripts attached. Running both is reasonable: webhooks for the live path, a scheduled pull to catch anything a failed delivery dropped.
How do I check a webhook really came from TranscriptHook?
Check the X-VidProxy-Signature header. It is v1= followed by a hex HMAC-SHA256, keyed with your account's signing secret from Dashboard → Settings → Webhook signing, of the X-VidProxy-Timestamp value, a dot, and the raw request body. Compute it over the raw bytes before any JSON parsing, compare in constant time, and reject timestamps more than 5 minutes old. Verifying is optional: the signature headers are additive, and a receiver that ignores them keeps working. Regenerating the secret invalidates the old one immediately. Node, Python and n8n examples are in Verifying webhook signatures.
When does a transcript lookup spend a credit?
Only when it returns a transcript. A lookup for a video with captions disabled, or one that simply fails, costs nothing. Every response carries an X-Credits-Remaining header, and the quota resets on the 1st of each month: 10 on Free, 500 on Starter, 2,500 on Pro, 10,000 on Agency. Past the quota the endpoint answers 402 credits_exhausted. The get_transcript MCP tool draws on the same pool; webhook deliveries and the pull API never touch it.
Why is transcript_available false on a video I know has captions?
Usually because the captions weren't there yet. YouTube generates auto-captions after a video goes live — normally within minutes, sometimes hours. TranscriptHook holds delivery until the transcript is confirmed and retries on a widening schedule (first after about 10 minutes, then at growing intervals up to every 4 hours); after about 24 hours it stops waiting and delivers the video with transcript.available set to false. If you'd rather have the metadata immediately, turn off Wait for transcript before delivering on the subscription. A durable false means YouTube reports captions as disabled for that video, which no amount of retrying changes.
Why did a video arrive hours after it was published?
Almost always because YouTube wouldn't tell us about it yet. New videos are detected through YouTube's public RSS feed, and that endpoint is intermittently unavailable for a few hours most nights — it answers 404 or 500 for channels that are plainly fine, then clears on its own. We currently see it between roughly 01:00 and 07:00 UTC, though the hours drift and other people using the same feed report a different window, so treat that range as an observation rather than a schedule. It's a long-standing YouTube issue, publicly reported since December 2025 and still open; it isn't specific to TranscriptHook and there's no setting on either side that avoids it.

Nothing is dropped. The feed carries a channel's last 15 uploads and we re-read it every cycle, so the first successful read picks up everything published while it was refusing us. It only costs you a video if a channel publishes more than 15 during the window. Transcripts are unaffected — that's a separate path, and a video detected late still arrives with its transcript attached.
What happens when I hit the rate limit?
You get a 429, with Retry-After giving the seconds until the window clears. Two budgets are checked per API key: a burst per-minute window and a sustained per-day window — 15/min (100/day) on Free, 20/min (300/day) on Starter, 60/min (3,000/day) on Pro, 100/min (8,000/day) on Agency. A request has to fit under both. X-RateLimit-Remaining and X-RateLimit-Remaining-Day on every response let you back off before you get there. Calls to /mcp draw from that same per-key budget rather than a separate one, so splitting traffic across the two transports doesn't buy you extra headroom.
Does the MCP server need a paid plan?
No. All 11 tools are available on every plan, connected with OAuth or authenticated with the same API key as the REST API; your plan limits still apply through them — get_transcript spends a credit, add_channel counts against your channel limit. The exception is remove_channel: it is never available over OAuth, and over an API key it stays hidden and refused until you enable destructive tools in Dashboard → Settings (an account setting that applies to your API keys). It changes only when you toggle it.