Two ways to get YouTube transcripts: pull on your schedule, or receive them by webhook shortly after a new video drops.
The Pull API uses API key authentication. Create a key under Connect & API keys in the dashboard. Pass it using any of these methods:
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.
Fetch all transcripts detected for your subscriptions within a time window. Good for batch processing, scheduled jobs, or polling-based integrations.
| 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. |
curl https://transcripthook.com/api/videos?since=24h&tag=my-channel \ -H "Authorization: Bearer tr_live_xxxxxxxxxxxx"
{
"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"
}
}
| 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. |
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.
| Parameter | Type | Description |
|---|---|---|
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. |
curl "https://transcripthook.com/api/transcript?video_id=dQw4w9WgXcQ" \ -H "Authorization: Bearer tr_live_xxxxxxxxxxxx"
{
"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
}
| Header | Description |
|---|---|
X-Credits-Remaining |
Lookups remaining this month. Agency starts at 10,000 (no plan is unlimited). |
| Status | Error | Meaning |
|---|---|---|
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. |
| Plan | Lookups / month |
|---|---|
| Free | 10 |
| Starter | 500 |
| Pro | 2,500 |
| Agency | 10,000 |
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.
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 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."
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.
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
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 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.
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.
| Tool | Description | Credits |
|---|---|---|
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.
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.
| Header | Value |
|---|---|
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. |
{
"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.
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:
X-VidProxy-Timestamp is more than 5 minutes away from your clock. That stops an old captured request being replayed.v1= + hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with your secret.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.
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:
If all of those fail, the delivery is kept and retried up to 5 more times, each one this long after the previous attempt:
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:
410 Gone;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.
Return any 2xx status code within 10 seconds. If your processing takes longer, acknowledge immediately and handle async.
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 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.
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.
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.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.
filtered · no keyword match.skipped · no transcript to match.paused · filter not in your plan) until you clear it; clearing always works.| Method | Endpoint | Description |
|---|---|---|
GET | /api/keyword-alerts | List all keyword alerts |
POST | /api/keyword-alerts | Create a keyword alert — body: { "keyword": "string" } |
DELETE | /api/keyword-alerts/:id | Delete a keyword alert |
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:
| Header | Description |
|---|---|
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.
| 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 |
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.
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.
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.
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.
false means YouTube reports captions as disabled for that video, which no amount of retrying changes.
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.
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.
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.