Monitors and webhooks · TranscriptFetch docs

Watch a YouTube channel or a TikTok or Instagram profile, and receive each new video as a signed webhook, optionally with its transcript.
A monitor watches a YouTube channel or a TikTok or Instagram profile, and tells you about every video that appears after you create it. Each check that finds new videos records one event, POSTs it to your webhook with a signature, and keeps it readable from the events endpoint; with transcripts: true the event carries each new video's transcript as well. It is the push version of polling a channel with since_video_id.
The platform is read from the target, so there is nothing else to choose. type is optional: channel is the only type and the default.
On YouTube a monitor can be narrower: tab (videos, shorts or live) watches the channel's uploads, which is the default, its Shorts or its live streams; a creator who posts only Shorts needs shorts. sort and query are not available on monitors. The monitor lists what it was given under options.
A monitor's target and tab are fixed; create another monitor to watch something else. Pinned posts and reordered tabs keep surfacing old videos, so a monitor passes over anything published more than 24 hours before it was created.
From an AI assistant, the MCP server has the same monitors as tools: create_monitor, list_monitors, get_new_videos, check_monitor_now and delete_monitor, with the same limits and credits. A monitor made on one is the same monitor on the other.
Playlists and searches are not watched. Monitors cover channels and profiles only. Read a playlist or run a search on demand with the playlist and search endpoints; a playlist or search monitor is refused with 400 invalid_request.
Creating a monitor lists its target once, for 1 credit, like any check. A channel or profile that does not exist is refused with 404 not_found; otherwise its first page today is recorded as already seen (baseline_count says how many), so you only hear about videos that appear from now on. The monitor is then checked every interval_minutes: 15, 60, 360 or 1440, default 60. webhook_url, interval_minutes, transcripts and name can all be changed later.
Store webhook_secret now. The 201 response is the only place it appears, and every delivery is signed with it. There is no way to read it again: if you lose it, delete the monitor and create a new one.
Each check that finds new videos sends one POST to webhook_url, with the event as its JSON body:
type is monitor.videos and data.videos holds the new rows exactly as the listing endpoints return them. With transcripts: true, data.transcripts has one entry per video: ok with the transcript, error with the standard error block, or processing while it is still on its way. A transcript that arrives later is sent as its own monitor.transcript event, whose data.videos_event_id names the event that announced the video.
Every delivery carries these headers:
Answer with any 2xx within 10 seconds. Anything else (another status, a timeout, a redirect, which is never followed, or an unreachable host) is retried after 1, 5, 30, 120 and 720 minutes, and after 6 attempts the delivery is marked failed. A delivery can arrive more than once, so deduplicate on X-TranscriptFetch-Delivery. Webhooks are optional: every event, delivered or not, stays readable from GET /api/v2/monitors/{monitorId}/events for 30 days, with a delivery block saying where it stands.
Compute the HMAC over the exact bytes you received, before parsing them, and compare in constant time. The key is the whole secret, whsec_ prefix included.
Read the raw body the way your framework exposes it: express.raw({ type: "application/json" }) in Express, await req.text() in a Next.js route handler, request.get_data() in Flask, await request.body() in FastAPI. Answer 401 to a delivery whose signature does not match, and parse the JSON only once it does.
No webhook needed: every monitor tells you whether it has found anything since you last looked. has_new is true or false, and last_event_id names the newest event.
Reading never marks anything as read: you pass back what you last saw, so a dashboard, a script and a retry never take the news from each other. Without since, has_new means the monitor has found something in the last 30 days. An id older than that counts as older than every event, so has_new can only err towards true.
Every check costs 1 credit, the price of one listing page, whether it finds new videos or nothing, and however many it finds. So does the first read when the monitor is created. A check whose listing fails is free. With transcripts: true, each caption transcript costs 1 credit, and a video without captions goes to AI Fallback Transcription at 1 credit per started 5 minutes of audio (minimum 1), billed when the transcript is delivered. Brand-new YouTube uploads usually get automatic captions some minutes after they go live, so YouTube captions are retried every 15 minutes for up to 60 minutes before AI Fallback Transcription is used.
If the account cannot pay when a check finds videos, nothing is recorded: the videos are not marked seen, the monitor's last_error reads insufficient_credits, and the first check after you top up delivers them. Listing, reading, changing and deleting monitors, and reading their events, are free.
Creating a monitor past the cap answers 400 monitor_limit_reached, and an interval shorter than the plan allows is refused with 400 invalid_request. Monitors need an API key from TranscriptFetch itself: they are not available through a marketplace subscription such as RapidAPI, whose billing cannot meter scheduled checks. Every field, response and error is in the monitor endpoints below.
Every call for creating and managing monitors: parameters, request and response, with Try it to send a live call.
Watch a YouTube channel or a TikTok or Instagram profile, and receive every new video as an event, by webhook and from the events endpoint. Creation reads the target once, for 1 credit like any check, t