Monitors & webhooks guide
Supported URLs
All URL formats- Handle
@veritasium - Handle URL
https://www.youtube.com/@veritasium - Channel ID
UCHnyfMqiRRG1u-2MsSQLbXA - Channel ID URL
https://www.youtube.com/channel/UCHnyfMqiRRG1u-2MsSQLbXA - Custom channel URL
https://www.youtube.com/c/veritasium - Legacy user URL
https://www.youtube.com/user/veritasium
Body parameters
- type
"channel"- required
false- default
"channel"- description
- Optional;
"channel"is the only type and the default. - Monitors watch a YouTube
channelor a TikTok or Instagram profile. "playlist"and"search"are refused: read those on demand with the playlist and search endpoints.
- Optional;
- type
string- required
true- description
- The YouTube channel (@handle, UC… id or URL) or the TikTok or Instagram profile URL, in any form the channel endpoint accepts.
- The platform is read from it.
- Fixed for the life of the monitor.
- type
string- required
false- values
youtubetiktokinstagram- description
- Not needed: the platform is read from target.
- If you send it anyway it must agree with the target.
- type
string- required
false- default
"videos"- values
videosshortslive- description
- YouTube channel monitors only: which tab to watch.
videos(the default) is the channel's uploads,shortsits Shorts,liveitslivestreams (past and upcoming).- A creator who posts only Shorts has an empty Videos tab, so a monitor on their uploads never fires: watch their
shorts. - Refused on TikTok and Instagram, like the channel endpoint refuses it; fixed once the monitor is created.
- type
string (https URL) | null- required
false- description
- Where to POST each event.
- The body is the event object (the same object the events endpoint lists, without its delivery block); X-TranscriptFetch-Event carries its
typeand X-TranscriptFetch-Delivery its id, which stays the same across retries of one event. - Every delivery is signed: X-TranscriptFetch-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the monitor's
webhook_secret(the whole string, whsec_ prefix included). - Verify it over the exact bytes you received, before parsing, and compare in constant time.
- Answer with any 2xx within 10 seconds.
- A failed attempt (another status, a timeout, a redirect, which is never followed, or an unreachable host) is retried after 1, 5, 30, 120 and 720 minutes, then the delivery is marked failed; each event's delivery block shows where it stands.
- With transcripts:
truea delivery carries the full transcripts, so accept bodies of several megabytes. - Must be a public https URL on the standard port.
- It is checked when saved and again before every delivery, so an address that stops resolving publicly receives nothing.
- Optional: every event is also readable from the events endpoint.
- Send
nullon PATCH to remove it.
- type
integer- required
false- default
60- values
15603601440- description
- Minutes between checks; default
60, or the plan's shortest interval when that is longer (1440without a paid plan). - Accounts without a paid plan may use
1440; any paid plan also15,60,360. - A new interval takes effect from the moment it is saved.
- Should the account leave its paid plan, a monitor keeps its setting but is not checked more often than the plan then allows.
- Minutes between checks; default
- type
boolean- required
false- default
false- description
- Also deliver each new video's transcript, fetched the way a batch entry is in
"auto"mode. - Caption transcripts arrive inline in the monitor.videos event and cost 1 credit each.
- A video with no captions is transcribed by AI Fallback Transcription instead, billed on delivery (1 credit per started 5 minutes of audio, minimum 1), and its transcript follows in its own monitor.transcript event; until then its entry reads
"processing". - Brand-new YouTube uploads usually have no automatic captions yet, so YouTube captions are retried every 15 minutes for up to 60 minutes after the video is found before AI Fallback Transcription is used: a caption transcript costs 1 credit where a 20-minute video through AI Fallback Transcription costs 4.
- TikTok and Instagram videos without captions go straight to AI Fallback Transcription.
- An upcoming or ongoing live stream has no transcript until its recording exists: it is looked for every 30 minutes for up to 7 days, and the caption grace period starts when the stream has ended.
- A caption transcript the balance cannot cover is not sent: it waits for credits for up to 7 days, then is reported as failed with
insufficient_credits. - A key with the captions-only policy never transcribes audio, here as anywhere: transcripts it turned on, or that a check it ran left owed, are captions only, and a video still without captions after the grace period is reported as failed (
no_captions). - Default
false.
- Also deliver each new video's transcript, fetched the way a batch entry is in
- type
boolean- required
false- default
false- description
- Beta.
- With transcripts on, adds
markdownto every transcript this monitor delivers (see the transcript endpoint). - Change it later with PATCH.
- Free.
- Shown on the monitor only when set.
- type
boolean | { max_tokens, overlap_tokens }- required
false- description
- Beta.
- With transcripts on, adds
chunksto every transcript this monitor delivers: pieces for an embedding model, each with start, end, a link to that moment and its token count (see the transcript endpoint). trueusesmax_tokens500 andoverlap_tokens50; an object sets either.- On PATCH,
falseturns them off. - Free.
- Shown on the monitor only when set.
- type
string (up to 100) | null- required
false- description
Your label for the monitor, returned on the monitor and in every event it produces.
Created
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "monitor",
"id": "mon_m3k1x9qz4vb2p7",
"type": "channel",
"platform": "youtube",
"target": "@lexfridman",
"options": {
"tab": "videos"
},
"name": "Lex Fridman uploads",
"status": "active",
"has_new": true,
"last_event_id": "mev_m3k1xa0b7c8d9e",
"interval_minutes": 60,
"transcripts": true,
"webhook_url": "https://example.com/hooks/transcriptfetch",
"next_check_at": "2026-09-25T15:00:12.000Z",
"last_checked_at": null,
"last_error": null,
"created_at": "2026-09-24T09:12:40.000Z",
"updated_at": "2026-09-24T09:12:40.000Z",
"webhook_secret": "whsec_…",
"baseline_count": 30
},
"usage": {
"credits_spent": 0,
"balance": 250
}
}Every YouTube endpoint
- POSTTranscriptText or segments for a YouTube video.
- POSTSearchSearch YouTube with date and length filters.
- POSTChannel VideosList a YouTube channel's videos.
- POSTPlaylistList a playlist's videos, page by page.
- POSTShortsList a channel's Shorts to transcribe.
- POSTChannel MonitorNew uploads from a channel, by webhook.
Same call, other platforms:TikTok Profile Monitor APIInstagram Profile Monitor API
Frequently asked questions
How is this different from polling the channel endpoint with since_video_id?
Polling is a call you schedule and pay a credit for whenever something is new. A monitor runs the schedule for you, pushes each new video to your webhook or the events list, and can fetch the transcript on your behalf. Use polling for one script, a monitor for a product.
What does a monitor cost?
Every check costs 1 credit, the price of one listing page, whether or not it finds new videos, plus 1 credit per caption transcript when transcripts is true; AI Fallback Transcription is billed at its rate on delivery. Monitor and interval limits depend on the plan and are stated on the endpoint.
Can a monitor watch a channel's Shorts or live streams?
Yes. Create it with tab shorts or tab live. A creator who posts only Shorts has an empty Videos tab, so a monitor on their uploads never fires; watch their shorts instead. The tab is fixed once the monitor exists.
How do I verify a webhook came from TranscriptFetch?
Compute HMAC-SHA256 of the exact request bytes with the monitor's webhook_secret and compare it, in constant time, with the X-TranscriptFetch-Signature header (sha256= followed by the hex digest). X-TranscriptFetch-Delivery identifies the delivery across retries.
Why does a brand-new upload take a while to get a transcript?
YouTube's automatic captions usually appear some minutes after publishing. The monitor retries captions for a grace period before falling back to AI Fallback Transcription, because a caption transcript costs 1 credit where a long video through AI Fallback Transcription costs more.