Frequently asked questions
Straight answers, including the parts that are still rough.
What is an API? (in plain words)
An API is a way for one program to ask another program for information. Think of a restaurant waiter: you tell the waiter what you want, and the waiter brings it back from the kitchen. ytapis is a waiter for YouTube. Your app asks for “videos about cats”, and ytapis brings back the list.
You don’t need to understand the details to use the playground. Click “Search”, type a word, and you will see real results.
Is it really free?
Yes. There is no API key, no OAuth and no sign-up. The hosted API reads public data from YouTube’s web interface. The maintainer runs the hosted endpoint, so uptime and limits are not guaranteed. If you depend on it heavily, consider hosting your own copy from the repository.
Is this the official YouTube API?
No. ytapis is an independent, unofficial project. It is not affiliated with, endorsed by or sponsored by YouTube or Google. Because it reads public pages, it can break when YouTube changes its pages.
Which languages are supported?
The repository contains client code for 11 languages, plus a CLI and an MCP server. Our checks on 9 October 2026:
- Verified in a sandbox: TypeScript (ytapis-core) and Python (ytapis).
- Published, not run here: Dart (pub.dev) and Go (source in repo).
- Installs, but needs a workaround: CLI and MCP server. See the Libraries page.
- Not found on the registry at check time: C#, Kotlin, Rust and PHP.
Why does npm install ytapis fail?
There is no npm package with that name. The TypeScript package is ytapis-core. Install it with npm install ytapis-core.
What does the search endpoint return?
The HTTP API returns a plain JSON array of video objects, not an object wrapped in { results: [...] }. The SDKs wrap the array in a response object, so check which one you use.
How does pagination work?
In the SDKs, search returns a continuation token. Pass it to searchContinue() in TypeScript or search_continue() in Python to get the next page. Over plain HTTP, no token is handed out, so ask for a larger limit instead (the upper limit is 50, and YouTube may return fewer).
Why do some endpoints return an empty list?
On 9 October 2026, trending, comments, related, transcript, channel uploads and playlists returned [] in our tests. The endpoints work and return correctly shaped responses, but the upstream data was empty. This can change at any time. The endpoint reference shows the status we measured, and the playground tells you live when a result is empty.
What are the rate limits?
There is no official limit. Aggressive use can trigger CAPTCHAs or 429 responses from YouTube. Cache results, space out bulk requests by about half a second, and retry with exponential backoff. The errors page has code for all three.
Do the gl and hl region parameters work?
No. The worker reads only q and limit for search, lang for transcripts, and limit for the other list routes. It does not read gl or hl, so they have no effect over HTTP. The comments route also ignores sort.
Can I use it in a commercial product?
No. This is an educational project. The site and its hosted service are not intended for commercial purposes, such as selling a product, charging for access or earning money. See the Terms & conditions.
The open-source code in the GitHub repository is MIT-licensed. That licence covers the code itself. The hosted site and service are covered by our terms.
Can AI agents use ytapis?
Yes, and that is the point of the AI prompt page. Load the master prompt into Claude Code, OpenCode, Codex, Cursor, Gemini CLI, Copilot or any other agent. It lists every endpoint, shape, limit and gotcha, so the agent builds against the real API.
Do the CLI and MCP server work?
Not with a plain npm install. Version 2.0.0 of both depends on an old core package. Pin ytapis-core to 2.0.0 with an npm overrides entry, as shown on the Libraries page. We verified that fix in a sandbox.
How does the API get its data?
There is no official API behind it. The Cloudflare Worker requests public YouTube pages and reads the data YouTube embeds in them:
- Search, trending, channel and playlist: the results page HTML, parsed from ytInitialData.
- Video info: ytInitialPlayerResponse from the watch page. If that is missing, the worker falls back to YouTube’s oEmbed endpoint for the title and author.
- Stats and live status: the watch page, which gives view counts and a live flag.
- Comments and related videos: YouTube’s internal youtubei/v1/next endpoint, called with the key found in the watch page.
- Transcripts: the captionTracks URL from the watch page, then the caption XML.
When a parser cannot find the expected data, the worker returns an empty list or placeholder values with status 200. This is why empty responses are common. A change to YouTube’s page structure can break a route until the worker is updated.
Why does the comments count in stats always show 0?
The worker hard-codes comments: 0 in /video/:id/stats. To get comments, call /video/:id/comments and count the items.
Why is isLive false on /video/:id?
The worker never sets isLive or isUpcoming on the video route. For live state, use /video/:id/live. Its isUpcoming is also unreliable, so check isLive and scheduledStartTime together.
Can I pass a channel handle like @name?
Not for channel metadata. We tested /channel/@RickAstleyYT/metadata on 9 October 2026, and it returned the empty object with the handle as the ID. Use the UC… channel ID instead.
Who built this?
ytapis was built by geethudino, and this website is hosted by Sree Jeevan. The source is on GitHub. Issues and pull requests are welcome.
Still have a question?
Try the playground, or ask your AI agent with the master prompt loaded.