API reference
Endpoint reference
A dedicated endpoint per source, fetch one video, list a channel, playlist, or search, and batch up to 50 transcripts in a single call. All requests and responses are JSON, and every authenticated endpoint expects a bearer token.
POST/api/v1/transcripts/videoidempotent
Returns a video's transcript - text plus timestamped segments. Accepts YouTube, TikTok, Instagram, X (Twitter), and Facebook URLs, plus direct media file URLs. When no captions exist, the audio is transcribed automatically (202 + job to poll). Every failure carries an ai_fallback block saying whether captions were definitively unavailable and whether retrying with ai_fallback:true would work.
Body parameters
videostringrequired
A video URL or 11-character YouTube video ID. Accepts YouTube (watch, youtu.be, /shorts/), TikTok, Instagram, X (Twitter), and Facebook URLs, plus direct media file URLs (mp4/mp3/wav/…). Videos without captions fall back to AI transcription automatically.
ai_fallbackbooleanoptional
Skip the caption fetch and transcribe the audio with AI instead. Send this after a failed request whose ai_fallback.available was true. Returns 202 with a job to poll; 1 credit is charged only when the transcript is delivered.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "transcript",
"video_id": "dQw4w9WgXcQ",
"platform": "youtube",
"title": "Example video",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
"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": 99,
"bytes": 14233
}
}POST/api/v1/webidempotent
Fetches any http(s) URL and returns the main readable content as clean Markdown plus page metadata - navigation, ads, and boilerplate removed. Built for RAG and LLM pipelines.
Body parameters
urlstring (url)required
The http(s) URL of the web page to fetch and convert to Markdown.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "web",
"url": "https://example.com/article",
"title": "Example article",
"markdown": "# Example article\n\nClean, boilerplate-free content …",
"metadata": {
"author": "Jane Doe",
"date": "2026-01-15",
"description": "A short summary of the page.",
"sitename": "Example"
}
},
"usage": {
"credits_spent": 1,
"balance": 99,
"bytes": 48211
}
}POST/api/v1/web/mapidempotent
Returns every same-site link found on a page plus its sitemap.xml - the fast way to discover a site's URLs before crawling or scraping them. 1 credit per call.
Body parameters
urlstring (url)required
The http(s) URL of the web page to fetch and convert to Markdown.
limitinteger (1–500)optional
Max links to return. Defaults to 200.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "web_map",
"url": "https://example.com",
"links": [
"https://example.com/about",
"https://example.com/blog/post-1"
],
"count": 2,
"total_found": 48
},
"usage": {
"credits_spent": 1,
"balance": 99,
"bytes": 61240
}
}POST/api/v1/web/crawlidempotent
Breadth-first crawl from a start URL across same-site links, returning clean Markdown for every readable page (up to 25 per call). Bills 1 credit per page returned.
Body parameters
urlstring (url)required
The http(s) URL of the web page to fetch and convert to Markdown.
limitinteger (1–25)optional
Max pages to crawl. Defaults to 10.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "web_crawl",
"url": "https://example.com/docs",
"pages": [
{
"url": "https://example.com/docs",
"title": "Docs",
"markdown": "# Docs\n\n…"
},
{
"url": "https://example.com/docs/quickstart",
"title": "Quickstart",
"markdown": "# Quickstart\n\n…"
}
],
"count": 2,
"visited": 6
},
"usage": {
"credits_spent": 2,
"balance": 97,
"bytes": 183002
}
}POST/api/v1/transcripts/channelidempotent
Resolve a channel into a paginated list of videos (metadata only), newest first. Pass since_video_id to get back only the uploads newer than one you've already seen - a page with nothing new is free, which makes this safe to poll on a schedule.
Body parameters
channelstringrequired
Channel @handle, /channel/UC… URL, or UC… ID.
limitinteger (1–50)optional
Max videos to return per page. Defaults to 5.
cursorstringoptional
Opaque pagination cursor from a previous response's next_cursor. Omit for the first page.
since_video_idstringoptional
Newest video ID you have already seen. The response is trimmed to videos newer than it, and a page with nothing newer costs no credits - so you can poll a channel for new uploads for free.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "video_list",
"source": "channel_videos",
"videos": [
{
"videoId": "dQw4w9WgXcQ",
"title": "Example video",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
"duration": 212,
"channel": "Example Channel"
}
],
"next_cursor": "eyJvIjoxMH0"
},
"usage": {
"credits_spent": 1,
"balance": 98,
"bytes": 0
}
}POST/api/v1/transcripts/playlistidempotent
Resolve a playlist into a paginated list of videos (metadata only).
Body parameters
playliststringrequired
Playlist URL or playlist ID.
limitinteger (1–50)optional
Max videos to return per page. Defaults to 5.
cursorstringoptional
Opaque pagination cursor from a previous response's next_cursor. Omit for the first page.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "video_list",
"source": "playlist",
"videos": [
{
"videoId": "dQw4w9WgXcQ",
"title": "Example video",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
"duration": 212,
"channel": "Example Channel"
}
],
"next_cursor": "eyJvIjoxMH0"
},
"usage": {
"credits_spent": 1,
"balance": 98,
"bytes": 0
}
}POST/api/v1/transcripts/searchidempotent
Resolve a keyword search into a paginated list of videos (metadata only).
Body parameters
querystringrequired
Keyword search query.
limitinteger (1–50)optional
Max videos to return per page. Defaults to 5.
cursorstringoptional
Opaque pagination cursor from a previous response's next_cursor. Omit for the first page.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "video_list",
"source": "search",
"videos": [
{
"videoId": "dQw4w9WgXcQ",
"title": "Example video",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
"duration": 212,
"channel": "Example Channel"
}
],
"next_cursor": "eyJvIjoxMH0"
},
"usage": {
"credits_spent": 1,
"balance": 98,
"bytes": 0
}
}POST/api/v1/transcripts/batchidempotent
Fetch transcripts for up to 50 video IDs concurrently. Charges 1 credit per successfully fetched transcript; failed or blocked videos are free.
Body parameters
videoIdsstring[] (1–50)required
Video IDs or URLs. Full YouTube URLs are normalized automatically.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "transcript_batch",
"results": [
{
"video_id": "dQw4w9WgXcQ",
"outcome": "ok",
"title": "Example video",
"text": "Full transcript text …",
"segments": [
{
"start": 0,
"duration": 3.5,
"text": "Full transcript …"
}
],
"cached": true,
"bytes": 14233
},
{
"video_id": "9bZkp7q19f0",
"outcome": "no_transcript",
"title": null,
"text": null,
"segments": null,
"cached": false,
"bytes": 0
}
]
},
"usage": {
"credits_spent": 1,
"balance": 97
}
}GET/api/v1/me
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.
Body parameters
No request body, this endpoint takes no parameters.
Example request
Response
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "me",
"user_id": "user_…",
"credits": 250
},
"usage": {
"credits_spent": 0,
"balance": 250,
"bytes": 0
}
}GET/api/v1/healthno auth
Public liveness probe for uptime monitoring. Returns 200 whenever the API is serving. No authentication required and no credits used.
Body parameters
No request body, this endpoint takes no parameters.
Example request
Response
{
"status": "ok",
"service": "transcriptfetch-api",
"version": "1.0.0",
"time": "2026-06-16T00: 00: 00.000Z"
}