{"openapi":"3.1.0","info":{"title":"TranscriptFetch API","version":"2.0.0","description":"Fetch video transcripts from YouTube, TikTok, and Instagram, plus direct media file URLs. Videos without a caption track are transcribed automatically. The list endpoints resolve a channel or profile, a playlist, or a keyword search into video lists, and on YouTube also list a channel's Shorts, live streams, playlists or podcasts and find channels and playlists by keyword. Monitors watch a YouTube channel or a TikTok or Instagram profile on a schedule and deliver each new video to a signed webhook. Successful (`ok`) caption fetches and list pages cost 1 credit each. A video with no captions is transcribed by AI Fallback Transcription by default (mode \"auto\"), which costs 1 credit per started 5 minutes of audio (minimum 1 credit), billed on delivery; send mode \"captions\" to never pay for audio. Requests that fail or return no transcript are free."},"servers":[{"url":"https://transcriptfetch.com","description":"Production"}],"externalDocs":{"description":"Documentation","url":"https://transcriptfetch.com/docs"},"security":[{"bearerAuth":[]}],"tags":[{"name":"Transcripts","description":"Transcript and video-list endpoints"},{"name":"Monitors","description":"Watch channels, playlists and searches for new videos"},{"name":"Jobs","description":"Channel jobs: a whole channel's transcripts as one background job"},{"name":"System","description":"Service health and metadata"}],"paths":{"/api/v2/transcripts/video":{"post":{"tags":["Transcripts"],"summary":"Fetch a transcript (YouTube, TikTok, Instagram, or file URL)","description":"Returns a transcript - text plus timestamped segments. Accepts YouTube, TikTok, and Instagram URLs (or a bare TikTok video id) and direct media file URLs. By default (mode \"auto\") a video with no captions is transcribed by AI Fallback Transcription, charged on delivery at 1 credit per started 5 minutes of audio; send mode \"captions\" to never pay for audio. When we can determine the media length, media under 20 minutes simply waits (the request is held open for up to 45 seconds) and returns the finished transcript, so no polling is needed; when the length cannot be determined, only short-form platforms (TikTok and Instagram) are held inline. Longer media, or a transcription still running when the 45-second hold expires, returns 202 with a job to poll instead - the work continues either way, so the same request is safe to retry and will hit the cache once it finishes. Supply callback_url to have the finished transcript POSTed to you instead of polling. A captions-only miss names the mode that would work in error.retry_with.","operationId":"fetchVideoTranscript","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"},"examples":{"example":{"value":{"video":"dQw4w9WgXcQ"}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"transcript","video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","platform":"youtube","title":"Example video","channel":"Example Channel","duration":212,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg","source":"captions","segments":[{"start":0,"duration":3.5,"text":"We're no strangers to love"}]},"usage":{"credits_spent":1,"balance":99,"bytes":14233}}}}}}},"202":{"description":"Accepted - AI Fallback Transcription started. Poll poll_url for the result, or supply callback_url to have it delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAcceptedEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/v2/transcripts/channel":{"post":{"tags":["Transcripts"],"summary":"List a channel's or profile's videos, Shorts, streams or playlists","description":"Resolve a creator into a paginated list of videos (metadata only), newest first. A channel or profile that does not exist answers 404 not_found; an existing one with no uploads answers 200 with an empty list. The platform is read from the input: a YouTube channel, or a TikTok or Instagram profile URL. Every row's url is accepted by the transcript and batch endpoints as-is. Pass since_video_id to get back only the items newer than one you've already seen; each such poll costs 1 credit, whether or not it finds new items. A YouTube channel also takes tab (its Shorts, live streams, playlists or podcasts instead of its videos), sort (popular or oldest first) and query (search inside the channel). The playlists and podcasts tabs answer with data.kind playlist_list, whose rows' urls the playlist endpoint accepts as-is.","operationId":"fetchChannelVideos","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelRequest"},"examples":{"example":{"value":{"channel":"@lexfridman","limit":10}},"shorts":{"summary":"A channel's Shorts","value":{"channel":"@lexfridman","tab":"shorts","limit":10}},"playlists":{"summary":"A channel's playlists (data.kind playlist_list)","value":{"channel":"@lexfridman","tab":"playlists","limit":10}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"video_list","source":"channel_videos","platform":"youtube","videos":[{"videoId":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","title":"Example video","duration":212,"channel":"Example Channel","publishedAt":"2009-10-25T00:00:00Z","stats":{"plays":1600000000}}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}},"shorts":{"summary":"A channel's Shorts","value":{"ok":true,"request_id":"req_…","data":{"kind":"video_list","source":"channel_videos","platform":"youtube","videos":[{"videoId":"Tq8mN2vXa4E","url":"https://www.youtube.com/watch?v=Tq8mN2vXa4E","title":"Example Short","duration":42,"channel":"Example Channel","publishedAt":"2026-09-21T00:00:00Z","stats":{"plays":318000}}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}},"playlists":{"summary":"A channel's playlists (data.kind playlist_list)","value":{"ok":true,"request_id":"req_…","data":{"kind":"playlist_list","source":"channel","platform":"youtube","playlists":[{"playlistId":"PLrAXtmRdnEQy6nuLMt9H1aZIuhcGOcZQ4","url":"https://www.youtube.com/playlist?list=PLrAXtmRdnEQy6nuLMt9H1aZIuhcGOcZQ4","title":"Example playlist","channel":"Example Channel","videoCount":42}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/v2/transcripts/playlist":{"post":{"tags":["Transcripts"],"summary":"List a playlist's videos","description":"Resolve a playlist into a paginated list of videos (metadata only). A playlist that does not exist or is not public answers 404 not_found. The platform is read from the input: a YouTube playlist or a TikTok playlist URL. Instagram has no public playlists; list the profile through the channel endpoint instead.","operationId":"fetchPlaylistVideos","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistRequest"},"examples":{"example":{"value":{"playlist":"PLrAXtmRdnEQy6nuLMt9H1aZIuhcGOcZQ4","limit":10}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"video_list","source":"playlist","platform":"youtube","videos":[{"videoId":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","title":"Example video","duration":212,"channel":"Example Channel","publishedAt":"2009-10-25T00:00:00Z","stats":{"plays":1600000000}}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/v2/transcripts/search":{"post":{"tags":["Transcripts"],"summary":"Search for videos, channels or playlists","description":"Resolve a keyword search into a paginated list of videos (metadata only). Searches YouTube by default; set platform to search TikTok or Instagram instead. Every video row carries a url the transcript endpoint accepts unchanged, plus duration and publish time where the source provides them. On YouTube, upload_date, duration and captions filter the videos and sort orders them, and type finds channels (data.kind channel_list) or playlists (data.kind playlist_list) instead, whose rows' urls the channel and playlist endpoints accept as-is.","operationId":"searchVideos","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"examples":{"example":{"value":{"query":"how transformers work","platform":"tiktok","limit":10}},"filtered":{"summary":"Long YouTube videos with captions from this month, most viewed first","value":{"query":"how transformers work","upload_date":"month","duration":"long","sort":"views","captions":true,"limit":10}},"channels":{"summary":"Channels matching a search (data.kind channel_list)","value":{"query":"machine learning","type":"channel","limit":10}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"video_list","source":"search","platform":"tiktok","videos":[{"videoId":"7398765432101234567","url":"https://www.tiktok.com/@examplecreator/video/7398765432101234567","title":"the post caption","duration":58,"channel":"@examplecreator","publishedAt":"2026-08-30T14:02:00Z","stats":{"plays":1240000}}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}},"filtered":{"summary":"Long YouTube videos with captions from this month, most viewed first","value":{"ok":true,"request_id":"req_…","data":{"kind":"video_list","source":"search","platform":"youtube","videos":[{"videoId":"Hq3Lz8pVt2K","url":"https://www.youtube.com/watch?v=Hq3Lz8pVt2K","title":"Transformers, explained step by step","duration":1580,"channel":"Example Channel","publishedAt":"2026-09-08T00:00:00Z","stats":{"plays":184000}}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}},"channels":{"summary":"Channels matching a search (data.kind channel_list)","value":{"ok":true,"request_id":"req_…","data":{"kind":"channel_list","source":"search","platform":"youtube","channels":[{"channelId":"UCq9Xb2Lh7Tn4Wz8Pd1Kf6Ra","url":"https://www.youtube.com/channel/UCq9Xb2Lh7Tn4Wz8Pd1Kf6Ra","handle":"@examplechannel","title":"Example Channel","subscribers":1200000,"videoCount":null,"description":"Machine learning explained from first principles, one video at a time."}],"next_cursor":"eyJvIjoxMH0"},"usage":{"credits_spent":1,"balance":98,"bytes":0}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/v2/transcripts/jobs/{jobId}":{"get":{"tags":["Transcripts"],"summary":"Poll an AI Fallback Transcription job","description":"Returns the state of an AI Fallback Transcription job, created when a request escalated past captions. 200 for any job your account owns (an unknown id, or a job belonging to someone else, is a 404): read the status field, which is \"processing\" while the job is running (with a progress object: the step it is on, pieces transcribed out of the total, and a percent that moves only on those real counters), \"completed\" with the transcript in data, or \"failed\" with an error. The job_id and a ready-to-use poll_url come back in the 202 that started it. Free to poll on our side - credits are charged once, on delivery (1 credit per started 5 minutes of audio, minimum 1). NOTE for RapidAPI subscribers: every poll is still a billable request on your Hub plan, so prefer callback_url, or simply re-send the original request once the job has had time to finish (the result is cached, so it returns instantly and the delivery is charged once, not twice). Most transcriptions never reach this endpoint at all: when we can determine the media length, media under 20 minutes is returned synchronously, and short-form platforms (TikTok and Instagram) are held inline even when we cannot.","operationId":"getTranscriptJob","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","status":"completed","job_id":"asr_m3k1x9qz4vb2p7","data":{"kind":"transcript","video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","platform":"youtube","title":"Example video","channel":"Example Channel","duration":212,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg","source":"audio","text":"We're no strangers to love …","segments":[{"start":0,"duration":3.5,"text":"We're no strangers to love"}]},"usage":{"credits_spent":1,"balance":942,"bytes":18244}}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/transcripts/batch":{"post":{"tags":["Transcripts"],"summary":"Fetch up to 500 transcripts in one call (plan-dependent)","description":"Fetch a batch of transcripts concurrently. Batch size follows your plan: up to 50 entries on the free tier, Basic and Pro, and up to 500 on Mega and Scale (a request over your plan's cap fails whole with a clear error before anything is fetched or charged). Accepts the same inputs as /transcripts/video - YouTube, TikTok and Instagram URLs as well as bare YouTube IDs. Charges 1 credit per successfully fetched caption transcript; failed videos are free. Under the default mode \"auto\", entries with no caption track are transcribed by AI Fallback Transcription: those come back with outcome \"processing\" and a job_id, cost nothing on this call, and are charged on delivery at 1 credit per started 5 minutes of audio. Re-send the same batch once they have finished and the text is returned normally - polling is optional. Send mode: \"captions\" to never pay for audio: captionless entries then fail with error code no_captions.","operationId":"fetchTranscriptsBatch","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"examples":{"example":{"value":{"video_ids":["dQw4w9WgXcQ","https://www.tiktok.com/@user/video/7137723462233555205"],"mode":"auto"}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"transcript_batch","results":[{"video_id":"dQw4w9WgXcQ","outcome":"ok","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","title":"Example video","channel":"Example Channel","duration":212,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg","source":"captions","text":"Full transcript text …","segments":[{"start":0,"duration":3.5,"text":"Full transcript …"}],"bytes":14233},{"video_id":"9bZkp7q19f0","outcome":"processing","job_id":"asr_…","poll_url":"/api/v2/transcripts/jobs/asr_…"},{"video_id":"jNQXAC9IVRw","outcome":"error","error":{"code":"no_captions","number":4103,"message":"No caption track (manual or auto-generated) is available.","docs":"https://transcriptfetch.com/docs/errors/no_captions","retry_with":{"mode":"auto"}}}]},"usage":{"credits_spent":1,"balance":97}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/monitors":{"post":{"tags":["Monitors"],"summary":"Create a monitor for new videos","description":"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, to learn what is already there.\n\n- Baseline: a channel or profile that does not exist answers 404 not_found. Everything on its first page today is recorded as already seen, baseline_count says how many, so only videos that appear later are reported.\n- Each check, every interval_minutes, reads the newest 30 rows and reports the ones it has not seen as one monitor.videos event, sent to webhook_url when one is set and always readable from the events endpoint. One check reports at most 50 videos; any more are reported by the next checks.\n- Billing: every check costs 1 credit, whether it finds new videos or nothing, and so does the baseline read when the monitor is created. With transcripts: true, each caption transcript costs 1 more. A find is charged before its event is recorded or delivered; a check whose listing fails is free.\n- An account that cannot pay records nothing: the videos are not marked seen, last_error reads insufficient_credits, the monitor stays active, and the same videos are delivered by the first check after credits return.\n- Limits: 5 monitors and a 1440-minute minimum interval without a paid plan, 100 monitors and 15 minutes on any paid plan. Creating past the cap answers monitor_limit_reached.\n- A monitor does not report a video published more than 24 hours before it was created (pinned posts and reordered tabs keep resurfacing old videos).\n- YouTube channels: tab chooses the uploads (default), the Shorts or the live streams; a creator who posts only Shorts needs tab: \"shorts\". Fixed once created.\n- Monitors watch channels and profiles only. A playlist or search type is refused with invalid_request; read those on demand with the playlist and search endpoints.\n- The 201 response carries webhook_secret, the key every delivery is signed with. It is shown this once: store it.","operationId":"createMonitor","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorRequest"},"examples":{"example":{"value":{"target":"@lexfridman","webhook_url":"https://example.com/hooks/transcriptfetch","interval_minutes":60,"transcripts":true,"name":"Lex Fridman uploads"}},"shorts":{"summary":"A channel's Shorts (a creator who posts only Shorts)","value":{"target":"@lexfridman","tab":"shorts","webhook_url":"https://example.com/hooks/transcriptfetch"}},"tiktok":{"summary":"A TikTok profile","value":{"target":"https://www.tiktok.com/@nasa"}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCreatedEnvelope"},"examples":{"example":{"value":{"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}}},"shorts":{"summary":"A channel's Shorts (a creator who posts only Shorts)","value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor","id":"mon_m3k1x9qz4vb2p7","type":"channel","platform":"youtube","target":"@lexfridman","options":{"tab":"shorts"},"name":null,"status":"active","has_new":true,"last_event_id":"mev_m3k1xa0b7c8d9e","interval_minutes":60,"transcripts":false,"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}}},"tiktok":{"summary":"A TikTok profile","value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor","id":"mon_m3k1x9qz4vb2p7","type":"channel","platform":"tiktok","target":"https://www.tiktok.com/@nasa","options":{},"name":null,"status":"active","has_new":true,"last_event_id":"mev_m3k1xa0b7c8d9e","interval_minutes":60,"transcripts":false,"webhook_url":null,"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}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["Monitors"],"summary":"List your monitors","description":"Every monitor on the account, newest first, with the account's monitor limits (max_monitors is null when uncapped). Free. A monitor's webhook_secret is never returned here.\n\n- has_new at the top is true when any monitor has found something after since (without since: when any has found anything in the retention window); each monitor's has_new says which. last_event_id at the top is the account's newest event: pass it back as since next time to ask, in one call, whether anything is new.","operationId":"listMonitors","parameters":[{"name":"since","in":"query","required":false,"description":"The last_event_id you saw last time. has_new then says whether anything arrived after it (and on the events endpoint, only newer events are listed). Reading never marks anything as read: pass back the id you last saw, so any number of readers and retries stay correct. Events share one sequence across your monitors, so the list's last_event_id works as since for the whole list. An id that is no longer kept (older than the retention window, or deleted with its monitor) counts as older than every event, so has_new can only err towards true.","schema":{"type":"string","pattern":"^mev_[a-zA-Z0-9]{6,40}$"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorListEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor_list","has_new":true,"last_event_id":"mev_m3k1xa0b7c8d9e","monitors":[{"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":"2026-09-25T14:00:09.000Z","last_error":null,"created_at":"2026-09-24T09:12:40.000Z","updated_at":"2026-09-24T09:12:40.000Z"}],"limits":{"max_monitors":100,"min_interval_minutes":15}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/monitors/{monitorId}":{"get":{"tags":["Monitors"],"summary":"Get a monitor","description":"One monitor: its settings, when it was last checked and is next due (null while paused), last_error, the error block of the last check that failed or could not be paid for (null once a check succeeds), and whether it has found anything new. A monitor that belongs to another account answers 404, like one that does not exist. Free.\n\n- has_new and last_event_id: last_event_id is the monitor's newest event. Keep it, send it back as since next time, and has_new answers whether anything arrived after it. Without since, has_new is true when the monitor has found anything in the retention window. Reading never marks anything as read.","operationId":"getMonitor","parameters":[{"name":"monitorId","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"The last_event_id you saw last time. has_new then says whether anything arrived after it (and on the events endpoint, only newer events are listed). Reading never marks anything as read: pass back the id you last saw, so any number of readers and retries stay correct. Events share one sequence across your monitors, so the list's last_event_id works as since for the whole list. An id that is no longer kept (older than the retention window, or deleted with its monitor) counts as older than every event, so has_new can only err towards true.","schema":{"type":"string","pattern":"^mev_[a-zA-Z0-9]{6,40}$"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEnvelope"},"examples":{"example":{"value":{"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":"2026-09-25T14:00:09.000Z","last_error":null,"created_at":"2026-09-24T09:12:40.000Z","updated_at":"2026-09-24T09:12:40.000Z"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Monitors"],"summary":"Update or pause a monitor","description":"Change a monitor's webhook_url, interval_minutes, transcripts, markdown, chunks, name or status: send only the fields to change. Free.\n\n- type, target, platform and tab are fixed: create a new monitor for a different target.\n- Pausing stops scheduled checks. Resuming checks at the next scheduler tick, from the saved state.","operationId":"updateMonitor","parameters":[{"name":"monitorId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMonitorRequest"},"examples":{"example":{"value":{"status":"paused"}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEnvelope"},"examples":{"example":{"value":{"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":"paused","has_new":true,"last_event_id":"mev_m3k1xa0b7c8d9e","interval_minutes":60,"transcripts":true,"webhook_url":"https://example.com/hooks/transcriptfetch","next_check_at":null,"last_checked_at":"2026-09-25T14:00:09.000Z","last_error":null,"created_at":"2026-09-24T09:12:40.000Z","updated_at":"2026-09-25T14:20:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Monitors"],"summary":"Delete a monitor","description":"Delete a monitor, its events and any transcripts it still owed; nothing more is checked or delivered for it. An AI Fallback Transcription already running finishes, is billed as usual, and stays readable from its job. Free.","operationId":"deleteMonitor","parameters":[{"name":"monitorId","in":"path","required":true,"schema":{"type":"string"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorDeletedEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor_deleted","id":"mon_m3k1x9qz4vb2p7"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/monitors/{monitorId}/events":{"get":{"tags":["Monitors"],"summary":"List a monitor's events","description":"The monitor's events, newest first, with cursor pagination, whether or not it has a webhook. Free.\n\n- monitor.videos carries the new rows exactly as the listing endpoints return them, and with transcripts: true one transcripts entry per video: ok with the transcript, processing, or error with the same error block a request-level failure carries.\n- monitor.transcript carries one follow-up transcript entry and videos_event_id, the event that announced the video.\n- Each event's delivery block reads none (no webhook), pending (next_attempt_at is the next try), delivered, or failed after 6 attempts.\n- Events are kept for 30 days.\n- since lists only the events after the one you last saw, newest first; with next_cursor the pages stop at since.","operationId":"listMonitorEvents","parameters":[{"name":"monitorId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Events per page, newest first. Defaults to 10; events can carry full transcripts, so pages are kept small.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page, as received. Omit it for the newest events.","schema":{"type":"string","maxLength":256}},{"name":"since","in":"query","required":false,"description":"The last_event_id you saw last time. has_new then says whether anything arrived after it (and on the events endpoint, only newer events are listed). Reading never marks anything as read: pass back the id you last saw, so any number of readers and retries stay correct. Events share one sequence across your monitors, so the list's last_event_id works as since for the whole list. An id that is no longer kept (older than the retention window, or deleted with its monitor) counts as older than every event, so has_new can only err towards true.","schema":{"type":"string","pattern":"^mev_[a-zA-Z0-9]{6,40}$"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventListEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor_event_list","monitor_id":"mon_m3k1x9qz4vb2p7","events":[{"id":"mev_m3k1xa0b7c8d9e","type":"monitor.videos","created_at":"2026-09-25T14:00:09.000Z","monitor":{"id":"mon_m3k1x9qz4vb2p7","name":"Lex Fridman uploads","type":"channel","platform":"youtube","target":"@lexfridman"},"credits_spent":2,"data":{"videos":[{"videoId":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","title":"Example video","duration":212,"channel":"Example Channel","publishedAt":"2026-09-25T13:00:00Z","stats":{"plays":1200}}],"transcripts":[{"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","outcome":"ok","transcript":{"kind":"transcript","video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","platform":"youtube","title":"Example video","channel":"Example Channel","duration":212,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg","source":"captions","text":"We're no strangers to love …","segments":[{"start":0,"duration":3.5,"text":"We're no strangers to love"}]}}]},"delivery":{"status":"delivered","attempts":1,"last_attempt_at":"2026-09-25T14:00:10.000Z","next_attempt_at":null,"last_error":null,"delivered_at":"2026-09-25T14:00:10.000Z"}}],"next_cursor":"eyJ0IjoiNDIifQ"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/monitors/{monitorId}/check":{"post":{"tags":["Monitors"],"summary":"Check a monitor now","description":"Run a check immediately, billed exactly like a scheduled one: 1 credit whether or not it finds videos (plus caption transcripts). The next scheduled check moves to one interval from now.\n\n- When it finds videos, the event's first webhook attempt has been made by the time this returns, so its delivery block shows whether your endpoint accepted it.\n- A listing that fails (the channel was deleted, the platform did not answer) is the check's result, not a failed request: 200 with new_videos 0, event null and data.error, the error block the monitor's last_error now shows. Nothing is charged.\n- Only a monitor that does not exist answers 404. An account that cannot pay answers 402 insufficient_credits, with nothing recorded.\n- A check of this monitor that is already running answers 429 with Retry-After, and so does one the scheduler took over partway: nothing it did was charged or recorded, and the scheduled check reports the videos.\n- Caption transcripts the check does not reach in time are not dropped: they follow as monitor.transcript events.\n- Works on a paused monitor too.","operationId":"checkMonitor","parameters":[{"name":"monitorId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCheckEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"monitor_check","monitor":{"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:21.000Z","last_checked_at":"2026-09-25T14:00:09.000Z","last_error":null,"created_at":"2026-09-24T09:12:40.000Z","updated_at":"2026-09-24T09:12:40.000Z"},"new_videos":1,"event":{"id":"mev_m3k1xa0b7c8d9e","type":"monitor.videos","created_at":"2026-09-25T14:00:09.000Z","monitor":{"id":"mon_m3k1x9qz4vb2p7","name":"Lex Fridman uploads","type":"channel","platform":"youtube","target":"@lexfridman"},"credits_spent":2,"data":{"videos":[{"videoId":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","title":"Example video","duration":212,"channel":"Example Channel","publishedAt":"2026-09-25T13:00:00Z","stats":{"plays":1200}}],"transcripts":[{"video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","outcome":"ok","transcript":{"kind":"transcript","video_id":"dQw4w9WgXcQ","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","platform":"youtube","title":"Example video","channel":"Example Channel","duration":212,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg","source":"captions","text":"We're no strangers to love …","segments":[{"start":0,"duration":3.5,"text":"We're no strangers to love"}]}}]},"delivery":{"status":"delivered","attempts":1,"last_attempt_at":"2026-09-25T14:00:10.000Z","next_attempt_at":null,"last_error":null,"delivered_at":"2026-09-25T14:00:10.000Z"}}},"usage":{"credits_spent":2,"balance":248}}}}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/v2/me":{"get":{"tags":["System"],"summary":"Validate your key & check balance","description":"Validates the API key and returns the account's remaining credit balance. Free - never billed. Useful for programmatic balance checks and as a credential test in integrations.","operationId":"me","externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"me","user_id":"user_…","credits":250},"usage":{"credits_spent":0,"balance":250,"bytes":0}}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/v2/jobs/channel":{"post":{"tags":["Jobs"],"summary":"Start a channel job","description":"Fetch a channel's or profile's transcripts as one job: it lists the channel a page at a time and fetches each page's transcripts in the background, then calls your webhook. Answers 202 at once; poll the job for progress and read its results a page at a time. Beta.\n\n- Billing as it goes, what the same work by hand costs: 1 credit per listing page with videos, 1 per caption transcript delivered, AI Fallback Transcription at its usual rate in mode auto. Failures are free; starting is free.\n- Limits: 1,000 videos a job and 1 job at a time on Free, Basic and Pro; 25,000 videos and 2 jobs at a time on Mega and Scale. Refused at the start: an account that cannot pay for even the first page (402 insufficient_credits), more max_videos than the plan allows (400), and a job past the plan's running jobs (409 job_limit_reached).\n- A YouTube channel lists up to about its newest 2,000 videos in one order (sort oldest reaches the other end); TikTok and Instagram profiles page all the way.\n- Running out of credits mid-way fails the job; results fetched so far stay readable.\n- Results are read back from the transcript cache: they stay readable for 7 days after the job finishes (results_expire_at).\n- The 202 carries webhook_secret when webhook_url is set, shown this once.","operationId":"createChannelJob","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelJobRequest"},"examples":{"example":{"value":{"channel":"@3blue1brown","max_videos":500,"transcripts":{"timestamps":false,"chunks":true},"webhook_url":"https://example.com/hooks/transcriptfetch"}}}}}},"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"channel_job","id":"cjob_m3k1x9qz4vb2p7","status":"queued","channel":"@3blue1brown","platform":"youtube","options":{},"since_video_id":null,"max_videos":500,"transcripts":{"mode":"captions","timestamps":false,"chunks":{"max_tokens":500,"overlap_tokens":50}},"webhook_url":"https://example.com/hooks/transcriptfetch","listed":0,"completed":0,"failed":0,"processing":0,"credits_spent":0,"error":null,"created_at":"2026-10-21T10:00:00.000Z","started_at":null,"finished_at":null,"results_expire_at":null,"poll_url":"/api/v2/jobs/channel/cjob_m3k1x9qz4vb2p7","webhook_secret":"whsec_…"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["Jobs"],"summary":"List channel jobs","description":"The account's 20 most recent channel jobs, newest first, without their results. Free.","operationId":"listChannelJobs","externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"channel_job_list","jobs":[{"kind":"channel_job","id":"cjob_m3k1x9qz4vb2p7","status":"running","channel":"@3blue1brown","platform":"youtube","options":{},"since_video_id":null,"max_videos":500,"transcripts":{"mode":"captions","timestamps":false,"chunks":{"max_tokens":500,"overlap_tokens":50}},"webhook_url":"https://example.com/hooks/transcriptfetch","listed":142,"completed":96,"failed":3,"processing":0,"credits_spent":98,"error":null,"created_at":"2026-10-21T10:00:00.000Z","started_at":"2026-10-21T10:00:20.000Z","finished_at":null,"results_expire_at":null,"poll_url":"/api/v2/jobs/channel/cjob_m3k1x9qz4vb2p7"}]}}}}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/jobs/channel/{channelJobId}":{"get":{"tags":["Jobs"],"summary":"Get a channel job and its results","description":"Progress (status queued, running, completed, failed or cancelled; listed, completed, failed, processing, credits_spent) and a page of results in listing order, each shaped like a batch entry with the job's transcript options applied. Free.\n\n- A result is pending (not fetched yet), ok, processing (AI Fallback Transcription running: job_id and poll_url) or error. An ok result whose words have left the cache answers expired: true.\n- Page with cursor: next_cursor is null once every listed result has been returned; a running job may list more later.","operationId":"getChannelJob","parameters":[{"name":"channelJobId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page of results. Omit for the first.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"channel_job","id":"cjob_m3k1x9qz4vb2p7","status":"running","channel":"@3blue1brown","platform":"youtube","options":{},"since_video_id":null,"max_videos":500,"transcripts":{"mode":"captions","timestamps":false,"chunks":{"max_tokens":500,"overlap_tokens":50}},"webhook_url":"https://example.com/hooks/transcriptfetch","listed":142,"completed":96,"failed":3,"processing":0,"credits_spent":98,"error":null,"created_at":"2026-10-21T10:00:00.000Z","started_at":"2026-10-21T10:00:20.000Z","finished_at":null,"results_expire_at":null,"poll_url":"/api/v2/jobs/channel/cjob_m3k1x9qz4vb2p7","results":[{"video_id":"aircAruvnKk","url":"https://www.youtube.com/watch?v=aircAruvnKk","outcome":"ok","title":"But what is a neural network? | Deep learning chapter 1","channel":"3Blue1Brown","duration":1120,"language":"en","thumbnail_url":"https://i.ytimg.com/vi/aircAruvnKk/mqdefault.jpg","source":"captions","text":"This is a 3. It's sloppily written …","chunks":[{"index":0,"text":"This is a 3. …","start":4.22,"end":139.18,"url":"https://www.youtube.com/watch?v=aircAruvnKk&t=4s","tokens":494}]}],"next_cursor":"25"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Jobs"],"summary":"Cancel a channel job","description":"Stops a queued or running job before its next step; nothing more is charged, and results fetched so far stay readable. A finished job is returned unchanged. Free.","operationId":"cancelChannelJob","parameters":[{"name":"channelJobId","in":"path","required":true,"schema":{"type":"string"}}],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"example":{"value":{"ok":true,"request_id":"req_…","data":{"kind":"channel_job","id":"cjob_m3k1x9qz4vb2p7","status":"cancelled","channel":"@3blue1brown","platform":"youtube","options":{},"since_video_id":null,"max_videos":500,"transcripts":{"mode":"captions","timestamps":false,"chunks":{"max_tokens":500,"overlap_tokens":50}},"webhook_url":"https://example.com/hooks/transcriptfetch","listed":142,"completed":96,"failed":3,"processing":0,"credits_spent":98,"error":null,"created_at":"2026-10-21T10:00:00.000Z","started_at":"2026-10-21T10:00:20.000Z","finished_at":"2026-10-21T10:05:00.000Z","results_expire_at":null,"poll_url":"/api/v2/jobs/channel/cjob_m3k1x9qz4vb2p7"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v2/health":{"get":{"tags":["System"],"summary":"Health check","description":"Public liveness probe for uptime monitoring. Returns 200 whenever the API is serving. No authentication required and no credits used.","operationId":"healthCheck","security":[],"externalDocs":{"description":"Full API reference: fields, response shape, and error codes","url":"https://transcriptfetch.com/docs/endpoints"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"examples":{"example":{"value":{"status":"ok","service":"transcriptfetch-api","version":"2.0.0","time":"2026-06-16T00:00:00.000Z"}}}}}}}}}},"webhooks":{"monitorEvent":{"post":{"tags":["Monitors"],"summary":"Monitor event delivery","description":"Sent to a monitor's webhook_url for every event. Verify before trusting it: compute the hex HMAC-SHA256 of the raw request body, keyed with the monitor's webhook_secret (the whole string, whsec_ prefix included), and compare it in constant time to the hex after sha256= in X-TranscriptFetch-Signature. Answer 2xx within 10 seconds; anything else is retried after 1, 5, 30, 120, 720 minutes, then given up. Redirects are not followed. The same event can arrive more than once (a retry after a lost acknowledgement), so deduplicate on X-TranscriptFetch-Delivery.","parameters":[{"name":"X-TranscriptFetch-Signature","in":"header","required":true,"description":"sha256=<hex HMAC-SHA256 of the raw body, keyed with webhook_secret>.","schema":{"type":"string"}},{"name":"X-TranscriptFetch-Event","in":"header","required":true,"description":"The event type.","schema":{"type":"string","enum":["monitor.videos","monitor.transcript"]}},{"name":"X-TranscriptFetch-Delivery","in":"header","required":true,"description":"The event id; the same on every retry of one event.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventBody"}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send your API key as `Authorization: Bearer <key>`."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (≤255 chars) to safely retry a request without being charged twice. Replays return the original response with `Idempotent-Replayed: true`. Reusing a key with a different body is a 409 conflict.","schema":{"type":"string","maxLength":255}}},"schemas":{"VideoRequest":{"type":"object","required":["video"],"properties":{"video":{"type":"string","minLength":1,"maxLength":2000,"description":"A video URL or 11-character YouTube video ID. Accepts YouTube (watch, youtu.be, /shorts/), TikTok, and Instagram URLs, plus direct media file URLs (mp4/mp3/wav/…). Under the default mode, a video without captions is transcribed by AI Fallback Transcription (see mode)."},"mode":{"type":"string","enum":["captions","audio","auto"],"default":"auto","description":"Where the text may come from. \"auto\" (the default) reads the caption track, and when there is none transcribes the audio with AI Fallback Transcription, charged on delivery at 1 credit per started 5 minutes of audio, minimum 1 (a 20-minute video is 4; the 4-hour cap is 48). \"captions\" reads an existing caption track only and answers 422 no_captions when there is none: the one mode that never charges for audio. \"audio\" skips captions and always uses AI Fallback Transcription, at the same rate. A caption fetch is always 1 credit. AI Fallback Transcription on short media may finish inline after a wait of up to 45 seconds; longer work returns 202 with a job to poll or deliver by callback."},"timestamps":{"default":true,"oneOf":[{"type":"boolean"},{"type":"string","enum":["none","segment"]}],"description":"Which form the transcript comes back in. true (the default) returns the `segments` array, each with start, duration and text. false returns a single joined `text` string instead. On the single-transcript 200 exactly one of the two is present, never both, since segments already contain every word the joined text does; job results and batch entries carry both text and segments. The older strings \"segment\" and \"none\" mean the same two things and are still accepted."},"markdown":{"type":"boolean","default":false,"description":"Beta. true adds `markdown` to the transcript: a title line, a line with the channel, length and link, then paragraphs that each open with their time (linked to that moment on YouTube). Works with timestamps on or off. Free. Absent by default, so leaving it out changes nothing."},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}],"description":"Beta. Adds `chunks`: the transcript split into pieces sized for an embedding model or vector store. Each piece has index, text, start and end (seconds, null when the transcript has no timings), url (opens the video at start on YouTube; the item's link on other platforms) and tokens. Pieces break between caption lines, never mid-word, and overlap the previous piece slightly. true uses max_tokens 500 and overlap_tokens 50; an object sets either: max_tokens 100 to 2000, overlap_tokens 0 to 200 and smaller than max_tokens. Tokens are counted with OpenAI's o200k_base encoding. Free. Absent by default."},"callback_url":{"type":"string","format":"uri","maxLength":2000,"description":"Where to POST the finished transcript when a request escalates to AI Fallback Transcription, instead of polling the job. The delivery body is a trimmed envelope - {ok, status, job_id, data} on success, {ok, status, job_id, error} on failure - without the usage and request_id the poll URL adds. When a signing secret is configured on our side, the body is signed with HMAC-SHA256 over the exact bytes and sent as an X-TranscriptFetch-Signature: sha256=<hex> header so you can verify it came from us. Must be a public https URL on the standard port; the URL is checked again at delivery time, so an unreachable or private address still gets a 202 but never receives a delivery. The job stays pollable either way, so a missed delivery is never a lost transcript."},"ai_fallback":{"type":"boolean","default":false,"deprecated":true,"description":"Legacy alias for \"mode\", still supported. true is identical to \"mode\": \"audio\" (always AI Fallback Transcription); omitted or false is \"mode\": \"auto\", the default, which still uses AI Fallback Transcription when a video has no captions. Send one or the other, not both. false never turned the fallback off, which is why the field was replaced: send \"mode\": \"captions\" for that."}}},"ChannelRequest":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","minLength":1,"maxLength":2000,"description":"YouTube: @handle, /channel/UC… URL, or UC… ID. TikTok: profile URL (tiktok.com/@user). Instagram: profile URL (instagram.com/user/)."},"tab":{"type":"string","enum":["videos","shorts","live","playlists","podcasts"],"default":"videos","description":"YouTube channels only. Which tab to list: videos (the default), shorts, or live (streams: past broadcasts and upcoming ones). playlists and podcasts list the channel's playlists instead of its videos: data.kind is playlist_list, and each row's url is accepted by the playlist endpoint. A tab the channel does not have (live on a channel that has never streamed, say) answers 200 with an empty list, which is free, and a notice such as \"This channel has no Live tab.\""},"sort":{"type":"string","enum":["newest","popular","oldest"],"default":"newest","description":"YouTube channels only. Order of the videos, shorts or live tab: newest (the default), popular or oldest. popular is YouTube's own Popular order, most viewed first, and it leaves out videos with no views. Not accepted with the playlists and podcasts tabs."},"query":{"type":"string","minLength":1,"maxLength":200,"description":"YouTube channels only. Search inside this channel: the page holds its videos that match, rather than its latest uploads. Leave tab and sort unset."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Max items to return per page: videos, or the playlists or channels some listing options return. Defaults to 5."},"cursor":{"type":"string","maxLength":256,"description":"Opaque pagination cursor from a previous response's next_cursor (max 256 characters). Omit for the first page. Cursors are scoped to the listing that issued them, so send the same platform and listing options with each page. Offset-based sources cannot page past the first 2000 items."},"since_video_id":{"type":"string","minLength":1,"maxLength":2000,"description":"Newest video ID you have already seen. The response is trimmed to videos newer than it. A poll with since_video_id is a check for new uploads and costs 1 credit whether or not it finds any (a plain listing that comes back empty stays free). It needs newest-first videos: on a YouTube channel, the videos, shorts or live tab with the default sort and no query."}}},"PlaylistRequest":{"type":"object","required":["playlist"],"properties":{"playlist":{"type":"string","minLength":1,"maxLength":2000,"description":"YouTube: playlist URL or PL… ID. TikTok: playlist URL (tiktok.com/@user/playlist/name-id)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Max items to return per page: videos, or the playlists or channels some listing options return. Defaults to 5."},"cursor":{"type":"string","maxLength":256,"description":"Opaque pagination cursor from a previous response's next_cursor (max 256 characters). Omit for the first page. Cursors are scoped to the listing that issued them, so send the same platform and listing options with each page. Offset-based sources cannot page past the first 2000 items."}}},"SearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"Keyword search query."},"platform":{"type":"string","enum":["youtube","tiktok","instagram"],"default":"youtube","description":"Where to search: youtube (default), tiktok, or instagram. Every video result's url is accepted by the transcript and batch endpoints as-is. The type, upload_date, duration, sort and captions options search YouTube only."},"type":{"type":"string","enum":["video","channel","playlist"],"default":"video","description":"YouTube only. What to search for: video (the default), channel or playlist. Channels come back as data.kind channel_list, each row's url accepted by the channel endpoint; playlists as data.kind playlist_list, each row's url accepted by the playlist endpoint. A channel row carries the @handle, subscriber count and description; its videoCount is null, because YouTube's channel results no longer show one."},"upload_date":{"type":"string","enum":["hour","today","week","month","year"],"description":"YouTube video search only. Keep videos uploaded within the last hour, today, this week, this month or this year."},"duration":{"type":"string","enum":["short","medium","long"],"description":"YouTube video search only. Keep short (under 4 minutes), medium (4 to 20 minutes) or long (over 20 minutes) videos."},"sort":{"type":"string","enum":["relevance","views"],"default":"relevance","description":"YouTube only. Result order: relevance (the default) or views (most viewed first). YouTube search no longer sorts by upload date or rating, so neither is offered; for recent videos, filter with upload_date."},"captions":{"type":"boolean","default":false,"description":"YouTube video search only. true keeps only videos with subtitles or closed captions, whose transcripts come from captions rather than AI Fallback Transcription. Defaults to false: no filter."},"transcripts":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["captions","auto"],"default":"captions"},"timestamps":{"type":"boolean","default":true},"markdown":{"type":"boolean","default":false},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}]}}}],"description":"Beta. Video searches only. Adds a `transcript` to every video row, in the same shape as a batch entry (outcome ok, processing or error, with text, segments, and markdown or chunks when asked), so one call goes from a query to what the videos say. true fetches caption transcripts with timestamps; an object sets mode (\"captions\", the default, so a search never starts paid AI transcription unless you send \"auto\"), timestamps (false drops segments), markdown and chunks (see the transcript endpoint). limit can be at most 10 with it. Costs the page's credit plus 1 credit per caption transcript delivered; failures are free, and an account that cannot cover the page and every row is refused up front."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Max items to return per page: videos, or the playlists or channels some listing options return. Defaults to 5."},"cursor":{"type":"string","maxLength":256,"description":"Opaque pagination cursor from a previous response's next_cursor (max 256 characters). Omit for the first page. Cursors are scoped to the listing that issued them, so send the same platform and listing options with each page. Offset-based sources cannot page past the first 2000 items."}}},"BatchRequest":{"type":"object","required":["video_ids"],"properties":{"video_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","minLength":1,"maxLength":200},"description":"Video URLs or bare YouTube IDs, from any supported platform. Up to your plan's batch cap: 50 on free/Basic/Pro, 500 on Mega/Scale. Also accepted as the legacy key videoIds (send one or the other, not both)."},"mode":{"type":"string","enum":["auto","captions"],"description":"Where each entry's text may come from. \"auto\" (the default) reads captions and uses AI Fallback Transcription when there are none, charged on delivery at 1 credit per started 5 minutes of audio. \"captions\" reads an existing caption track only, so a captionless entry fails (error code no_captions) and nothing is charged for audio. \"audio\" is not accepted here: skipping captions for 50 videos at once is a job queue, not a batch fetch."},"markdown":{"type":"boolean","default":false,"description":"Beta. true adds `markdown` to the transcript: a title line, a line with the channel, length and link, then paragraphs that each open with their time (linked to that moment on YouTube). Works with timestamps on or off. Free. Absent by default, so leaving it out changes nothing."},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}],"description":"Beta. Adds `chunks`: the transcript split into pieces sized for an embedding model or vector store. Each piece has index, text, start and end (seconds, null when the transcript has no timings), url (opens the video at start on YouTube; the item's link on other platforms) and tokens. Pieces break between caption lines, never mid-word, and overlap the previous piece slightly. true uses max_tokens 500 and overlap_tokens 50; an object sets either: max_tokens 100 to 2000, overlap_tokens 0 to 200 and smaller than max_tokens. Tokens are counted with OpenAI's o200k_base encoding. Free. Absent by default."}}},"CreateMonitorRequest":{"type":"object","required":["target"],"properties":{"type":{"type":"string","enum":["channel"],"default":"channel","description":"Optional; \"channel\" is the only type and the default. Monitors watch a YouTube channel or a TikTok or Instagram profile. \"playlist\" and \"search\" are refused: read those on demand with the playlist and search endpoints."},"target":{"type":"string","minLength":1,"maxLength":2000,"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."},"platform":{"type":"string","enum":["youtube","tiktok","instagram"],"description":"Not needed: the platform is read from target. If you send it anyway it must agree with the target."},"tab":{"type":"string","enum":["videos","shorts","live"],"default":"videos","description":"YouTube channel monitors only: which tab to watch. videos (the default) is the channel's uploads, shorts its Shorts, live its live streams (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."},"webhook_url":{"type":["string","null"],"format":"uri","maxLength":2000,"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 type and 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: true a 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 null on PATCH to remove it."},"interval_minutes":{"type":"integer","enum":[15,60,360,1440],"default":60,"description":"Minutes between checks; default 60, or the plan's shortest interval when that is longer (1440 without a paid plan). Accounts without a paid plan may use 1440; any paid plan also 15, 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."},"transcripts":{"type":"boolean","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."},"markdown":{"type":"boolean","default":false,"description":"Beta. With transcripts on, adds `markdown` to every transcript this monitor delivers (see the transcript endpoint). Change it later with PATCH. Free. Shown on the monitor only when set."},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}],"description":"Beta. With transcripts on, adds `chunks` to 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). true uses max_tokens 500 and overlap_tokens 50; an object sets either. On PATCH, false turns them off. Free. Shown on the monitor only when set."},"name":{"type":["string","null"],"maxLength":100,"description":"Your label for the monitor, returned on the monitor and in every event it produces."}}},"UpdateMonitorRequest":{"type":"object","required":[],"properties":{"webhook_url":{"type":["string","null"],"format":"uri","maxLength":2000,"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 type and 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: true a 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 null on PATCH to remove it."},"interval_minutes":{"type":"integer","enum":[15,60,360,1440],"default":60,"description":"Minutes between checks; default 60, or the plan's shortest interval when that is longer (1440 without a paid plan). Accounts without a paid plan may use 1440; any paid plan also 15, 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."},"transcripts":{"type":"boolean","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."},"markdown":{"type":"boolean","default":false,"description":"Beta. With transcripts on, adds `markdown` to every transcript this monitor delivers (see the transcript endpoint). Change it later with PATCH. Free. Shown on the monitor only when set."},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}],"description":"Beta. With transcripts on, adds `chunks` to 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). true uses max_tokens 500 and overlap_tokens 50; an object sets either. On PATCH, false turns them off. Free. Shown on the monitor only when set."},"name":{"type":["string","null"],"maxLength":100,"description":"Your label for the monitor, returned on the monitor and in every event it produces."},"status":{"type":"string","enum":["active","paused"],"description":"paused stops scheduled checks. active resumes them at the next scheduler tick, from the saved state, so videos published while paused are reported by that check (as far as it reads: the newest page, and a YouTube playlist's end). Webhook retries and transcripts already owed continue while paused."}}},"ChannelJobRequest":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","minLength":1,"maxLength":2000,"description":"A YouTube channel (URL, @handle or UC… id), or a TikTok or Instagram profile URL: what the channel endpoint takes."},"platform":{"type":"string","enum":["youtube","tiktok","instagram"],"description":"youtube, tiktok or instagram. Read off the channel when omitted; a platform that contradicts it is refused."},"tab":{"type":"string","enum":["videos","shorts","live"],"description":"YouTube only: videos (the default), shorts or live."},"sort":{"type":"string","enum":["newest","popular","oldest"],"description":"YouTube only: newest (the default), popular or oldest."},"since_video_id":{"type":"string","maxLength":200,"description":"Stop at this video: only videos newer than it are fetched. Newest-first only (not with sort popular or oldest)."},"max_videos":{"type":"integer","minimum":1,"description":"The most videos to fetch. Defaults to, and is capped at, the plan's limit: 1,000 on Free, Basic and Pro, 25,000 on Mega and Scale."},"transcripts":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["captions","auto"],"default":"captions"},"timestamps":{"type":"boolean","default":true},"markdown":{"type":"boolean","default":false},"chunks":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"max_tokens":{"type":"integer","minimum":100,"maximum":2000,"default":500},"overlap_tokens":{"type":"integer","minimum":0,"maximum":200,"default":50}}}]}}}],"description":"What each video's transcript carries; the same options as a search with transcripts. Defaults to true: caption transcripts with timestamps. mode \"captions\" (the default) never starts paid AI transcription; \"auto\" sends captionless videos with speech to AI Fallback Transcription, and the job waits for them."},"webhook_url":{"type":"string","format":"uri","maxLength":2000,"description":"An https URL that receives channel_job.started, channel_job.completed and channel_job.failed, signed like monitor webhooks (X-TranscriptFetch-Signature). Best effort: the job itself is the record."}}},"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","properties":{"credits_spent":{"type":"integer"},"balance":{"type":["integer","null"],"description":"Remaining balance, or null for unlimited (admin) accounts."},"bytes":{"type":"integer"}}},"TranscriptChunk":{"type":"object","required":["index","text","start","end","url","tokens"],"description":"Beta. One piece of a transcript sized for an embedding model (request field chunks). Pieces break between caption lines and overlap the previous piece slightly.","properties":{"index":{"type":"integer","description":"Position, from 0."},"text":{"type":"string","description":"The words in this piece."},"start":{"type":["number","null"],"description":"Start in seconds; null when the transcript has no timings."},"end":{"type":["number","null"],"description":"End in seconds; null when the transcript has no timings."},"url":{"type":["string","null"],"description":"Opens the video at start on YouTube; the item's link on other platforms."},"tokens":{"type":"integer","description":"Size of text in tokens (OpenAI o200k_base)."}}},"Segment":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds."},"duration":{"type":"number","description":"Cue duration in seconds."},"text":{"type":"string"},"speaker":{"type":"integer","description":"Speaker id (0, 1, …) on diarized transcriptions only; absent everywhere else."}}},"Video":{"type":"object","description":"One row of a listing. `url` is accepted as-is by the transcript and batch endpoints. The platform is not repeated per row: the page's `platform` says it.","properties":{"videoId":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"duration":{"type":["number","null"],"description":"Seconds, when the source reports it."},"channel":{"type":["string","null"]},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Upload time. Exact for TikTok and Instagram; approximate on YouTube, whose listings only say \"2 days ago\", so it is exact to the day for recent videos and up to a year off for old ones."},"stats":{"type":["object","null"],"description":"Engagement counts where the source exposes them.","properties":{"plays":{"type":["integer","null"]}}},"transcript":{"type":"object","description":"Beta. Present when the search sent transcripts: this video's transcript in the shape of a BatchResult without video_id (outcome ok, processing or error; text, segments, markdown and chunks as asked)."}}},"SuccessEnvelope":{"type":"object","required":["ok","request_id","data","usage"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"oneOf":[{"$ref":"#/components/schemas/TranscriptData"},{"$ref":"#/components/schemas/VideoListData"},{"$ref":"#/components/schemas/PlaylistListData"},{"$ref":"#/components/schemas/ChannelListData"},{"$ref":"#/components/schemas/MeData"}],"discriminator":{"propertyName":"kind"}},"usage":{"$ref":"#/components/schemas/Usage"}}},"TranscriptData":{"type":"object","required":["kind","video_id","platform","source"],"description":"One shape for every transcript, whichever platform, rung or cache served it. Every metadata key is always present; null means unknown, never omitted.","properties":{"kind":{"type":"string","enum":["transcript"]},"video_id":{"type":"string","description":"The item's id on its platform: the 11-character YouTube id, TikTok's numeric id, the Instagram shortcode, or the URL for a direct file. (v1 echoes the value you sent instead.)"},"url":{"type":["string","null"],"description":"Canonical URL of the item, when known. Accepted as-is by every transcript endpoint."},"platform":{"type":"string","description":"Where the item lives.","enum":["youtube","tiktok","instagram","file"]},"title":{"type":["string","null"],"description":"Item title, or the post caption on TikTok and Instagram."},"channel":{"type":["string","null"],"description":"The creator, as the platform names them: a YouTube channel name, a TikTok @handle, an Instagram username, the uploader for a file. Same field as the listing rows."},"duration":{"type":["number","null"],"description":"Media length in seconds, when the source reports it."},"language":{"type":["string","null"],"description":"Language of the words: the caption track's code, or the language detected during AI Fallback Transcription. Null when neither reports one."},"thumbnail_url":{"type":["string","null"],"description":"Poster image for the item. TikTok and Instagram serve signed, expiring URLs, so copy the image rather than hotlinking it."},"source":{"type":"string","description":"Where the words came from: an existing caption track, or AI Fallback Transcription of the audio (billed by length, see usage.credits_spent).","enum":["captions","audio"]},"text":{"type":["string","null"],"description":"The words as one string. Present when timestamps is false; absent when segments is sent instead (batch, job and webhook bodies carry both)."},"segments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Segment"},"description":"Timestamped cues. Present by default; absent when text is sent instead."},"markdown":{"type":"string","description":"Beta. The transcript as Markdown with timestamped paragraphs. Present only when the request sent markdown: true."},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"},"description":"Beta. The transcript in pieces sized for an embedding model. Present only when the request sent chunks."}}},"VideoListData":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["video_list"]},"source":{"type":"string","description":"Which listing produced the page: channel, playlist or search."},"platform":{"type":"string","enum":["youtube","tiktok","instagram"],"description":"Where the rows came from: the `platform` field on search, the platform detected from the URL on channel and playlist."},"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"notice":{"type":"string","description":"Optional listing caveat, including upstream warnings when returned results may be incomplete, and \"This channel has no Live tab.\" (or Shorts) beside an empty list when a YouTube channel has no such tab."},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null when exhausted."}}},"Playlist":{"type":"object","description":"One row of a playlist_list. `url` is accepted as-is by the playlist endpoint; a podcast is a playlist too.","properties":{"playlistId":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":["string","null"]},"channel":{"type":["string","null"],"description":"The owning channel's name, when the listing shows it."},"videoCount":{"type":["integer","null"]}}},"Channel":{"type":"object","description":"One row of a channel_list. `url` is accepted as-is by the channel endpoint.","properties":{"channelId":{"type":"string"},"url":{"type":"string","format":"uri"},"handle":{"type":["string","null"],"description":"The channel's @handle."},"title":{"type":["string","null"]},"subscribers":{"type":["integer","null"],"description":"Subscriber count, read from YouTube's rounded label (1.2M is 1200000)."},"videoCount":{"type":["integer","null"],"description":"Null: YouTube's channel results no longer show a video count."},"description":{"type":["string","null"],"description":"Up to 300 characters."}}},"PlaylistListData":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["playlist_list"]},"source":{"type":"string","enum":["channel","search"],"description":"channel for a channel's playlists or podcasts tab, search for a playlist search."},"platform":{"type":"string","enum":["youtube"]},"playlists":{"type":"array","items":{"$ref":"#/components/schemas/Playlist"}},"notice":{"type":"string","description":"Optional listing caveat, such as \"This channel has no Podcasts tab.\" beside an empty list when the channel has no such tab."},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null when exhausted."}}},"ChannelListData":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["channel_list"]},"source":{"type":"string","enum":["search"],"description":"Always search: a channel search."},"platform":{"type":"string","enum":["youtube"]},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"notice":{"type":"string","description":"Optional listing caveat."},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null when exhausted."}}},"MeData":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["me"]},"user_id":{"type":"string"},"credits":{"type":["integer","null"],"description":"Remaining balance, or null for unlimited (admin) accounts."}}},"TranscriptJobData":{"type":"object","required":["kind"],"description":"Placeholder data block on a 202: identifies what is being transcribed while the job runs.","properties":{"kind":{"type":"string","enum":["transcript_job"]},"video_id":{"type":"string"},"platform":{"type":"string"}}},"JobAcceptedEnvelope":{"type":"object","required":["ok","request_id","status","job_id","poll_url"],"description":"Returned with HTTP 202 when a request escalates to AI Fallback Transcription. Poll poll_url (or wait for the callback_url delivery); credits are charged on delivery, not here.","properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"status":{"type":"string","enum":["processing"]},"job_id":{"type":"string"},"poll_url":{"type":"string","description":"Path of the job endpoint to poll, from the site root (/api/v2/transcripts/jobs/{job_id}): request it on https://transcriptfetch.com, not after a base URL that already ends in /api/v2."},"data":{"$ref":"#/components/schemas/TranscriptJobData"}}},"JobStatusEnvelope":{"type":"object","required":["ok","request_id","status","job_id"],"description":"Response of the job poll endpoint. data holds the transcript once status is completed and is null while processing (usage is absent then); a failed job has ok:false and an error block instead.","properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"job_id":{"type":"string"},"progress":{"$ref":"#/components/schemas/JobProgress"},"data":{"description":"The finished transcript; null until the job completes.","oneOf":[{"$ref":"#/components/schemas/TranscriptData"},{"type":"null"}]},"usage":{"$ref":"#/components/schemas/Usage"},"error":{"$ref":"#/components/schemas/ErrorBlock"}}},"JobProgress":{"type":"object","required":["stage","percent"],"description":"Where a processing job is, present only while status is processing. Stages run queued (waiting for a transcriber, queue_position jobs ahead), starting, audio (resolving and downloading the media; bytes when the source reports a size), transcribing (pieces_done of pieces_total) and finishing. percent is 0-99 across those steps and moves only on those real counters; 100 is the completed job.","properties":{"stage":{"type":"string","enum":["queued","starting","audio","transcribing","finishing"]},"percent":{"type":"integer","minimum":0,"maximum":99},"queue_position":{"type":["integer","null"]},"pieces_done":{"type":["integer","null"]},"pieces_total":{"type":["integer","null"]},"bytes_downloaded":{"type":["integer","null"]},"bytes_total":{"type":["integer","null"]}}},"BatchEnvelope":{"type":"object","required":["ok","request_id","data","usage"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"type":"object","properties":{"kind":{"type":"string","enum":["transcript_batch"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResult"}}}},"usage":{"$ref":"#/components/schemas/Usage"}}},"BatchResult":{"type":"object","required":["video_id","outcome"],"description":"One entry per requested video. Exactly three outcomes: \"ok\" carries the transcript, \"processing\" carries the audio-transcription job to poll, \"error\" carries the same error block a request-level failure does.","properties":{"video_id":{"type":"string"},"outcome":{"type":"string","enum":["ok","processing","error"]},"url":{"type":["string","null"],"description":"outcome \"ok\" only. Canonical URL of the item, when known. Accepted as-is by every transcript endpoint."},"title":{"type":["string","null"],"description":"outcome \"ok\" only. Item title, or the post caption on TikTok and Instagram."},"channel":{"type":["string","null"],"description":"outcome \"ok\" only. The creator, as the platform names them: a YouTube channel name, a TikTok @handle, an Instagram username, the uploader for a file. Same field as the listing rows."},"duration":{"type":["number","null"],"description":"outcome \"ok\" only. Media length in seconds, when the source reports it."},"language":{"type":["string","null"],"description":"outcome \"ok\" only. Language of the words: the caption track's code, or the language detected during AI Fallback Transcription. Null when neither reports one."},"thumbnail_url":{"type":["string","null"],"description":"outcome \"ok\" only. Poster image for the item. TikTok and Instagram serve signed, expiring URLs, so copy the image rather than hotlinking it."},"source":{"type":"string","enum":["captions","audio"],"description":"outcome \"ok\" only. Where the words came from: an existing caption track, or AI Fallback Transcription of the audio (billed by length, see usage.credits_spent)."},"text":{"type":["string","null"],"description":"outcome \"ok\" only."},"segments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Segment"},"description":"outcome \"ok\" only."},"bytes":{"type":"integer","description":"outcome \"ok\" only."},"markdown":{"type":"string","description":"outcome \"ok\" only, when the request sent markdown: true. Beta."},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"},"description":"outcome \"ok\" only, when the request sent chunks. Beta."},"job_id":{"type":"string","description":"outcome \"processing\" only: the audio-transcription job started for a captionless entry. Re-send the batch later or poll poll_url."},"poll_url":{"type":"string","description":"outcome \"processing\" only: path to poll for the finished transcript, from the site root (request it on https://transcriptfetch.com)."},"error":{"$ref":"#/components/schemas/ErrorBlock"}}},"ErrorBlock":{"type":"object","required":["code","number","message","docs"],"description":"Every failure carries this block. Branch on code (a stable string) or number (a stable integer whose thousands digit is the family: 1 request, 2 account, 3 input, 4 content, 5 transient, 9 ours; 5xxx means retry with backoff). At most one of retry_with, details, issues is present. Failures are never charged.","properties":{"code":{"type":"string","enum":["invalid_request","invalid_cursor","unauthorized","idempotency_conflict","not_found","insufficient_credits","batch_too_large","monitor_limit_reached","job_limit_reached","rate_limited","unsupported_platform","endpoint_platform_mismatch","audio_ineligible","invalid_input","audio_too_long","drm_protected","private","unavailable","members_only","age_restricted","region_blocked","not_public","live_stream","was_live","no_captions","captions_disabled","no_speech","no_audio_stream","no_video","upstream_error","timeout","connection","proxy_unavailable","parse_error","upstream_unavailable","internal_error","unknown"]},"number":{"type":"integer","enum":[1001,1002,1101,1201,1301,2001,2002,2003,2004,2101,3001,3002,3004,3005,3006,3007,4001,4002,4003,4004,4005,4006,4101,4102,4103,4104,4105,4106,4107,5001,5002,5003,5004,5005,5101,9001,9002]},"message":{"type":"string","description":"Prose for humans. Never parse it."},"docs":{"type":"string","format":"uri","description":"https://transcriptfetch.com/docs/errors/<code>"},"retry_with":{"type":"object","description":"Present when a different request would succeed: the fields to change, e.g. { \"mode\": \"auto\" } to transcribe a captionless video, or { \"endpoint\": \"/api/v2/transcripts/video\" } for a platform this endpoint does not list.","additionalProperties":true},"details":{"type":"object","description":"Structured specifics for the few codes that document one: batch_too_large { max, sent }, monitor_limit_reached { max, current }, job_limit_reached { max, current }.","additionalProperties":true},"issues":{"type":"array","description":"Field-level validation problems (invalid_request only).","items":{"type":"object"}}}},"ErrorEnvelope":{"type":"object","required":["ok","request_id","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"request_id":{"type":"string"},"error":{"$ref":"#/components/schemas/ErrorBlock"}}},"Monitor":{"type":"object","required":["kind","id","type","platform","target","options","status","has_new","last_event_id","interval_minutes","transcripts","created_at","updated_at"],"description":"A monitor. Its webhook_secret appears only in the response that created it.","properties":{"kind":{"type":"string","enum":["monitor"]},"id":{"type":"string","description":"The monitor's id (mon_…)."},"type":{"type":"string","enum":["channel"]},"platform":{"type":"string","enum":["youtube","tiktok","instagram"]},"target":{"type":"string"},"options":{"type":"object","description":"The listing options in effect, by their request field names: a YouTube channel's tab (videos unless set). Empty for TikTok and Instagram profiles.","properties":{"tab":{"type":"string","enum":["videos","shorts","live"]}}},"name":{"type":["string","null"]},"status":{"type":"string","enum":["active","paused"]},"has_new":{"type":"boolean","description":"Whether the monitor has an event after the since you passed; without since, whether it has found anything in the retention window. Reading never changes it: pass back last_event_id to move the mark."},"last_event_id":{"type":["string","null"],"description":"The monitor's newest event (mev_…), or null when it has found nothing yet. Send it as since next time."},"interval_minutes":{"type":"integer","enum":[15,60,360,1440]},"transcripts":{"type":"boolean"},"markdown":{"type":"boolean","enum":[true],"description":"Beta. Present (true) when the monitor's transcripts carry markdown."},"chunks":{"type":"object","description":"Beta. Present when the monitor's transcripts carry chunks: the sizes in effect.","properties":{"max_tokens":{"type":"integer"},"overlap_tokens":{"type":"integer"}}},"webhook_url":{"type":["string","null"],"format":"uri"},"next_check_at":{"type":["string","null"],"format":"date-time","description":"When the next scheduled check is due; null while paused."},"last_checked_at":{"type":["string","null"],"format":"date-time"},"last_error":{"description":"The last check that failed (the listing's error, e.g. not_found) or could not be paid for (insufficient_credits), as an error block plus when; null once a check succeeds.","oneOf":[{"$ref":"#/components/schemas/MonitorError"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MonitorError":{"type":"object","required":["code","number","message","docs","at"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_cursor","unauthorized","idempotency_conflict","not_found","insufficient_credits","batch_too_large","monitor_limit_reached","job_limit_reached","rate_limited","unsupported_platform","endpoint_platform_mismatch","audio_ineligible","invalid_input","audio_too_long","drm_protected","private","unavailable","members_only","age_restricted","region_blocked","not_public","live_stream","was_live","no_captions","captions_disabled","no_speech","no_audio_stream","no_video","upstream_error","timeout","connection","proxy_unavailable","parse_error","upstream_unavailable","internal_error","unknown"]},"number":{"type":"integer"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"},"at":{"type":"string","format":"date-time"}}},"MonitorSnapshot":{"type":"object","required":["id","type","platform","target"],"description":"The monitor an event came from, as it was when the event was recorded.","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":"string","enum":["channel"]},"platform":{"type":"string","enum":["youtube","tiktok","instagram"]},"target":{"type":"string"}}},"MonitorTranscriptEntry":{"type":"object","required":["video_id","url","outcome"],"description":"One video's transcript. \"ok\" carries it; \"processing\" means it follows as a monitor.transcript event (job_id when an AI Fallback Transcription job is running); \"error\" carries the same block a request-level failure does.","properties":{"video_id":{"type":"string","description":"The listing row's videoId."},"url":{"type":"string"},"outcome":{"type":"string","enum":["ok","processing","error"]},"transcript":{"$ref":"#/components/schemas/TranscriptData"},"job_id":{"type":"string"},"error":{"$ref":"#/components/schemas/ErrorBlock"}}},"MonitorVideosData":{"type":"object","required":["videos"],"description":"data of a monitor.videos event.","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"},"description":"The new rows, exactly as the listing endpoints return them."},"transcripts":{"type":"array","items":{"$ref":"#/components/schemas/MonitorTranscriptEntry"},"description":"One entry per video, in the same order; present only when the monitor has transcripts: true."}}},"MonitorTranscriptData":{"description":"data of a monitor.transcript event: one transcript entry, and the event that announced the video.","allOf":[{"$ref":"#/components/schemas/MonitorTranscriptEntry"},{"type":"object","required":["videos_event_id"],"properties":{"videos_event_id":{"type":"string"}}}]},"MonitorEventBody":{"type":"object","required":["id","type","created_at","monitor","credits_spent","data"],"description":"An event as a webhook delivery POSTs it.","properties":{"id":{"type":"string","description":"The event id (mev_…); also the X-TranscriptFetch-Delivery header."},"type":{"type":"string","enum":["monitor.videos","monitor.transcript"]},"created_at":{"type":"string","format":"date-time"},"monitor":{"$ref":"#/components/schemas/MonitorSnapshot"},"credits_spent":{"type":"integer","description":"What producing this event cost: 1 for the find plus 1 per inline caption transcript; on monitor.transcript, what that transcript cost (AI Fallback Transcription is billed by the job, on delivery)."},"data":{"oneOf":[{"$ref":"#/components/schemas/MonitorVideosData"},{"$ref":"#/components/schemas/MonitorTranscriptData"}]}}},"MonitorDelivery":{"type":"object","required":["status","attempts"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","failed"],"description":"none: no webhook. pending: next_attempt_at is the next try. failed: all 6 attempts failed."},"attempts":{"type":"integer"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"],"description":"Why the last attempt failed (e.g. HTTP 500, timeout)."},"delivered_at":{"type":["string","null"],"format":"date-time"}}},"MonitorEvent":{"allOf":[{"$ref":"#/components/schemas/MonitorEventBody"},{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/MonitorDelivery"}}}]},"MonitorEnvelope":{"type":"object","required":["ok","request_id","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"$ref":"#/components/schemas/Monitor"}}},"MonitorCreatedEnvelope":{"type":"object","required":["ok","request_id","data","usage"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"allOf":[{"$ref":"#/components/schemas/Monitor"},{"type":"object","required":["webhook_secret","baseline_count"],"properties":{"webhook_secret":{"type":"string","description":"whsec_… The key every delivery is signed with. Returned only here: store it."},"baseline_count":{"type":"integer","description":"Videos recorded as already seen at creation."}}}]},"usage":{"$ref":"#/components/schemas/Usage"}}},"MonitorListEnvelope":{"type":"object","required":["ok","request_id","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"type":"object","properties":{"kind":{"type":"string","enum":["monitor_list"]},"has_new":{"type":"boolean","description":"true when any monitor has an event after since (without since: when any has found anything in the retention window)."},"last_event_id":{"type":["string","null"],"description":"The account's newest event: pass it back as since next time. null when no monitor has found anything."},"monitors":{"type":"array","items":{"$ref":"#/components/schemas/Monitor"}},"limits":{"type":"object","properties":{"max_monitors":{"type":["integer","null"],"description":"null when uncapped."},"min_interval_minutes":{"type":"integer"}}}}}}},"MonitorDeletedEnvelope":{"type":"object","required":["ok","request_id","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"type":"object","properties":{"kind":{"type":"string","enum":["monitor_deleted"]},"id":{"type":"string"}}}}},"MonitorEventListEnvelope":{"type":"object","required":["ok","request_id","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"type":"object","properties":{"kind":{"type":"string","enum":["monitor_event_list"]},"monitor_id":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/MonitorEvent"}},"next_cursor":{"type":["string","null"],"description":"Pass back as cursor for older events; null at the end."}}}}},"MonitorCheckEnvelope":{"type":"object","required":["ok","request_id","data","usage"],"properties":{"ok":{"type":"boolean","enum":[true]},"request_id":{"type":"string"},"data":{"type":"object","required":["kind","monitor","new_videos","event"],"properties":{"kind":{"type":"string","enum":["monitor_check"]},"monitor":{"$ref":"#/components/schemas/Monitor"},"new_videos":{"type":"integer"},"event":{"oneOf":[{"$ref":"#/components/schemas/MonitorEvent"},{"type":"null"}]},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBlock"}],"description":"Present only when the check ran but its listing failed (the target is gone, or the platform did not answer): the same error the monitor's last_error now shows. Nothing was charged."}}},"usage":{"$ref":"#/components/schemas/Usage"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}