Guides
YouTube API (Data API v3): API key, quota, endpoints, transcripts and MCP servers
The YouTube API most people mean is the YouTube Data API v3: Google’s free REST interface at https://www.googleapis.com/youtube/v3 for searching YouTube and reading video, channel, playlist and comment data, plus uploading and managing your own channel. You get an API key in the Google Cloud console (create a project, enable “YouTube Data API v3”, then Credentials, Create credentials, API key), and Google charges nothing per call; instead, since June 1, 2026, each project gets 100 search.list calls a day, 100 uploads a day, and 10,000 quota units a day for everything else. The official API returns captions only for videos you can edit, so transcripts of other people’s videos are not available through it.
Every limit, price and rule below was read from Google’s YouTube developer docs, the YouTube API Services Terms and Developer Policies, and each project’s repository on November 15, 2026. Error bodies are ones we recorded that day.
YouTube Data API quota in November 2026
The Data API costs no money and is limited by quota. Google’s Quota Calculator states the default allocation as “100 search.list calls, 100 videos.insert calls, and 10,000 units per day combined for all other endpoints”. Quotas reset at midnight Pacific Time, and every request, including an invalid one, costs at least one unit.
| Method | Quota cost | Bucket |
|---|---|---|
search.list |
1 per call | Search Queries: 100 calls a day |
videos.insert (upload) |
1 per call | Uploads: 100 calls a day |
videos.list, channels.list, playlistItems.list, playlists.list |
1 | 10,000 units a day |
commentThreads.list, comments.list, activities.list, subscriptions.list |
1 | 10,000 units a day |
videos.batchGetStats (added June 3, 2026) |
1 | Its own bucket per Google’s revision note |
captions.list |
50 | 10,000 units a day |
captions.download |
200 | 10,000 units a day |
captions.insert / captions.update |
400 / 450 | 10,000 units a day |
Most writes: videos.update, playlistItems.insert, commentThreads.insert, thumbnails.set |
50 | 10,000 units a day |
liveChatMessages.list |
5 | 10,000 units a day |
Two rules change the arithmetic. Each extra page of results costs the same as the first page. And the search bucket is now the scarce one: 100 searches of up to 50 results each is at most 5,000 search results a day, while the 10,000-unit bucket covers thousands of videos.list calls.
Older guides are wrong about search. From November 11, 2014 until June 1, 2026, search.list cost 100 units out of the shared 10,000, so a project could run about 100 searches and nothing else. Google’s revision history records the June 1, 2026 move to “a granular quota system covering smaller sets of methods, starting with videos.insert and search.list”. The total number of searches did not change much (about 100 a day either way), but searching no longer eats the quota your videos.list and comment calls need. At least one MCP server README (kirbah/mcp-youtube) still prices its search tool at 100 units.
Quota changes with dates
| Date | Change |
|---|---|
| Nov 11, 2014 | search.list set to 100 units |
| Jul 29, 2020 | Extra cost per part removed; each method charges its base cost |
| Jul 1, 2021 | A compliance audit is required for more than the default 10,000 units |
| Dec 4, 2025 | Upload cost cut from about 1,600 units to about 100 |
| May 4, 2026 | Policy added for audited analytics developers who apply to compute extra metrics or store statistics longer |
| Jun 1, 2026 | search.list and videos.insert moved to their own buckets of 100 calls a day |
| Jun 3, 2026 | videos.batchGetStats added at 1 unit in its own bucket |
| Nov 2, 2026 | Uploads from unverified API projects are no longer forced to private |
The dates come from the Data API revision history and the Terms revision history.
Getting more quota
You cannot buy quota. To go past the default you complete an API Compliance Audit through the YouTube API Services Audit and Quota Extension Form, naming the use case; Google’s audit guide says a member of the API Services team will contact you. Approved quota may be used only for the approved use case, and a changed use case means a new audit. If you passed an audit in the last 12 months, the same form requests a further extension; a failed audit has its own appeals form. Google may also cut the quota of a project that has been inactive for 90 consecutive days. The Developer Policies set these rules.
Splitting one app across several projects or keys to multiply the default is the opposite of what the audit process is for. One popular MCP server’s README still shows three API keys as fallbacks.
How to get a YouTube API key, step by step
An API key reads public data only. You need a Google account.
- Open the Google Cloud console and create a project (or pick one).
- Go to APIs & Services, Library, search for YouTube Data API v3, open it and click Enable.
- Go to APIs & Services, Credentials, click Create credentials and choose API key.
- Add a restriction before you click Create. Google’s API key page says the console now requires at least one API restriction to create a key: choose YouTube Data API v3. Add an application restriction too (websites, IP addresses, or Android or iOS apps); Google’s wording is “Unrestricted API keys are insecure.”
- Copy the key string from the “API key created” dialog and keep it out of source control.
The same from the command line, with the gcloud CLI:
gcloud services enable youtube.googleapis.comgcloud services api-keys create \ --display-name="youtube-data" \ --api-target=service=youtube.googleapis.comTest it with one videos.list call (1 unit). Google accepts the key in the key query parameter or the x-goog-api-key header; the header keeps it out of URLs and logs:
export YOUTUBE_API_KEY=YOUR_API_KEYcurl -H "x-goog-api-key: $YOUTUBE_API_KEY" \ "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ"API key vs OAuth 2.0
Google’s authorization guide draws the line: an API key is for requests that “only retrieve public data, such as public video metadata or search results”, and OAuth 2.0 is required for anything that inserts, updates or deletes, and for private user data such as channels.list with mine=true.
| Task | API key | OAuth 2.0 |
|---|---|---|
| Search, public videos, channels, playlists, comments | Yes | Yes |
Your own channel (mine=true), private or unlisted videos |
No | Yes |
| Upload, edit, delete, comment, rate | No | Yes |
List or download caption tracks (captions.list, captions.download) |
No | Yes, with edit rights for download |
| YouTube Analytics and Reporting APIs | No | Yes |
For OAuth, create an OAuth client ID on the same Credentials page (Desktop app is simplest for scripts), download client_secret.json, and request the narrowest scope that works: youtube.readonly to view an account, youtube.force-ssl to edit videos, comments and captions, youtube.upload to upload. Access tokens expire; Google refreshes them at https://oauth2.googleapis.com/token with the refresh token, and users can revoke access from their Google Account permissions page.
Main Data API endpoints
All endpoints sit under https://www.googleapis.com/youtube/v3. Every list call takes a required part parameter naming the fields you want, such as snippet,statistics.
| Method and path | Returns | Auth | Quota | Page size |
|---|---|---|---|---|
search.list GET /search |
Videos, channels or playlists matching q, with filters for type, date, region, duration |
Key | 1, Search bucket | 0 to 50, default 5 |
videos.list GET /videos |
Full video records by comma-separated id, or a chart such as mostPopular |
Key | 1 | maxResults 1 to 50, not used with id |
videos.batchGetStats GET /videos:batchGetStats |
View, like and comment counts for a list of video IDs | Key for public videos | 1 | n/a |
channels.list GET /channels |
Channel records by id, forHandle (for example @GoogleDevelopers) or mine |
Key, or OAuth for mine |
1 | 0 to 50, default 5 |
playlistItems.list GET /playlistItems |
Videos in a playlist, including a channel’s uploads playlist | Key | 1 | 0 to 50, default 5 |
commentThreads.list GET /commentThreads |
Top-level comments and replies for a videoId or a whole channel |
Key | 1 | 1 to 100, default 20 |
captions.list GET /captions |
Caption track IDs and languages for a video, not the text | OAuth | 50 | n/a |
captions.download GET /captions/{id} |
One caption track as SRT, VTT, SBV, SCC or TTML | OAuth plus edit permission | 200 | n/a |
videos.insert POST /upload/youtube/v3/videos |
Uploads a video | OAuth | 1, Uploads bucket | n/a |
The cheapest way to list a channel’s videos skips search. Call channels.list with part=contentDetails, read contentDetails.relatedPlaylists.uploads, then page through that playlist with playlistItems.list. Google made the same point in 2014, when it put the search route at 100 units and this route at 6. A channel with 1,200 uploads costs 1 + 24 + 24 = 49 units this way, including full statistics from 24 videos.list calls of 50 IDs.
Python example: a channel’s videos with stats
This uses requests, sends the key in a header, counts quota as it goes, and lists a channel’s latest uploads with views and likes. For 200 videos it spends 9 units of the 10,000 and no searches.
import os
import requests
API_KEY = os.environ["YOUTUBE_API_KEY"]BASE_URL = "https://www.googleapis.com/youtube/v3"used = {"units": 0, "searches": 0}
def yt_get(resource, **params): """GET a Data API list method. Every call costs quota, even a failed one.""" if resource == "search": used["searches"] += 1 # Search Queries bucket: 100 calls a day else: used["units"] += 1 # list methods cost 1 unit (Quota Calculator, Nov 2026) resp = requests.get( f"{BASE_URL}/{resource}", params=params, headers={"x-goog-api-key": API_KEY}, timeout=30, ) data = resp.json() if resp.status_code != 200: err = data.get("error", {}) reason = (err.get("errors") or [{}])[0].get("reason") raise RuntimeError(f"{resp.status_code} {reason}: {err.get('message')}") return data
def uploads_playlist(handle): """Resolve a @handle to the channel's uploads playlist ID (1 unit).""" data = yt_get("channels", part="snippet,contentDetails", forHandle=handle) if not data.get("items"): raise ValueError(f"No channel for {handle}") channel = data["items"][0] return channel["snippet"]["title"], channel["contentDetails"]["relatedPlaylists"]["uploads"]
def latest_video_ids(playlist_id, limit=200): """Page through the uploads playlist, 50 items (1 unit) per page.""" ids, page_token = [], None while len(ids) < limit: params = {"part": "contentDetails", "playlistId": playlist_id, "maxResults": 50} if page_token: params["pageToken"] = page_token data = yt_get("playlistItems", **params) ids += [item["contentDetails"]["videoId"] for item in data.get("items", [])] page_token = data.get("nextPageToken") if not page_token: break return ids[:limit]
def video_details(video_ids): """Fetch titles and statistics in batches of 50 IDs (1 unit per batch).""" videos = [] for start in range(0, len(video_ids), 50): batch = ",".join(video_ids[start:start + 50]) data = yt_get("videos", part="snippet,statistics", id=batch) videos += data.get("items", []) return videos
if __name__ == "__main__": title, playlist = uploads_playlist("@GoogleDevelopers") videos = video_details(latest_video_ids(playlist, limit=200)) print(f"{title}: {len(videos)} videos, {used['units']} units, {used['searches']} searches") for video in videos[:5]: stats = video.get("statistics", {}) print( video["snippet"]["publishedAt"][:10], stats.get("viewCount", "?"), stats.get("likeCount", "hidden"), video["snippet"]["title"][:70], )To search instead, yt_get("search", part="snippet", q="model context protocol", type="video", maxResults=50) returns up to 50 results for one of your 100 daily searches; the video ID is in item["id"]["videoId"]. The API may return fewer than maxResults per page, so follow nextPageToken. Google’s official client library (pip install google-api-python-client) wraps the same calls as youtube.videos().list(...).
Captions and transcripts
The Data API gives you caption text only for videos you have permission to edit. Both caption read methods need OAuth: captions.list (50 units) returns track IDs and languages, but its response “does not contain the actual captions”. captions.download (200 units) “requires the user to have permission to edit the video”, per its reference page. For someone else’s video it returns 403 forbidden. There is no official endpoint for the transcript of a public video you do not own.
For your own channel, this downloads a track as SRT with Google’s client library (pip install google-api-python-client google-auth-oauthlib), following Google’s own captions sample:
from google_auth_oauthlib.flow import InstalledAppFlowfrom googleapiclient.discovery import build
SCOPES = ["https://www.googleapis.com/auth/youtube.force-ssl"]VIDEO_ID = "YOUR_OWN_VIDEO_ID"
flow = InstalledAppFlow.from_client_secrets_file("client_secret.json", SCOPES)creds = flow.run_local_server(port=0) # opens a browser for consent onceyoutube = build("youtube", "v3", credentials=creds)
tracks = youtube.captions().list(part="snippet", videoId=VIDEO_ID).execute() # 50 unitsfor track in tracks.get("items", []): print(track["id"], track["snippet"]["language"], track["snippet"]["trackKind"])
if tracks.get("items"): track_id = tracks["items"][0]["id"] srt = youtube.captions().download(id=track_id, tfmt="srt").execute() # 200 units print(srt[:500])Transcripts of videos you do not own
Open-source tools fill the gap by reading YouTube’s website rather than the Data API, and that is where the risk sits. The most used are jdepoix/youtube-transcript-api (Python, MIT, 8,616 stars, version 1.2.5 on PyPI released November 5, 2026) and yt-dlp/yt-dlp (208,050 stars), whose --write-subs, --write-auto-subs and --skip-download options save subtitle files without the video. Stated precisely:
- They are not the API. The transcript library’s README says it “uses an undocumented part of the YouTube API, which is called by the YouTube web-client”, with no guarantee it keeps working.
- YouTube’s Terms of Service (dated December 15, 2023) bar accessing the service “using any automated means (such as robots, botnets or scrapers)” except public search engines following robots.txt or with YouTube’s prior written permission.
- The API terms reach further. The Developer Policies say API clients must not “scrape YouTube Applications or Google Applications, or obtain scraped YouTube data or content”, and must not download, cache or store copies of YouTube audiovisual content without written approval. An app that uses an API key and also pulls transcripts with a scraper is outside the API agreement it accepted, not only the site terms.
- It breaks in production. The same README says YouTube “has started blocking most IPs that are known to belong to cloud providers”, so these libraries often fail on servers and push users toward rotating proxies.
Using a scraper for a one-off personal read is a different exposure from shipping it in a product, but neither is permitted by YouTube’s terms. This is a summary of the documents, not legal advice.
YouTube API errors with real response bodies
Errors come back as JSON with an HTTP status, a reason in error.errors[0], and a machine-readable ErrorInfo.reason. With no key at all, videos.list returned this on November 15, 2026:
{ "error": { "code": 403, "message": "Permission denied on the service.", "errors": [ {"message": "Permission denied on the service.", "domain": "global", "reason": "forbidden"} ], "status": "PERMISSION_DENIED", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "ACCESS_DENIED", "domain": "googleapis.com", "metadata": {"service": "youtube.googleapis.com"} } ] }}A wrong or deleted key, sent either way, returned:
{ "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "errors": [ {"message": "API key not valid. Please pass a valid API key.", "domain": "global", "reason": "badRequest"} ], "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "API_KEY_INVALID", "domain": "googleapis.com", "metadata": {"service": "youtube.googleapis.com"} } ] }}A bad OAuth token on captions.download returned 401 with "status": "UNAUTHENTICATED", "reason": "authError" and the message “Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.”
| Status and reason | Cause | Fix |
|---|---|---|
403 forbidden, ACCESS_DENIED |
No key and no token | Send x-goog-api-key or ?key= |
400 badRequest, API_KEY_INVALID |
Mistyped, deleted or wrong-project key | Copy the key again from Credentials |
403 quotaExceeded |
A bucket is used up for the day | Wait for midnight Pacific; cache; apply for an extension |
401 authError, UNAUTHENTICATED |
Expired or invalid OAuth access token | Refresh the token |
401 authorizationRequired |
mine=true or another private request sent with only a key |
Use OAuth |
403 insufficientPermissions |
OAuth token lacks the scope | Re-consent with the right scope |
403 forbidden on captions.download |
You cannot edit that video | Only your own videos’ captions are available |
403 commentsDisabled |
The video has comments turned off | Skip the video |
400 missingRequiredParameter |
Usually no part |
Add part=snippet |
404 videoNotFound; 403 channelNotFound |
Deleted, private or mistyped ID | Check the ID |
Reasons and descriptions come from Google’s errors reference. The 403, 400 and 401 bodies above are the ones we recorded; quotaExceeded was not observable without a key at its limit.
YouTube MCP servers for Claude, Cursor and ChatGPT
No official YouTube MCP server exists. Google’s YouTube docs describe none, Google Cloud’s list of managed MCP servers has no YouTube entry, and a search of the official MCP registry for “youtube” on November 15, 2026 returned 126 server names, none published by Google; most are hosted commercial transcript or data services. The open-source servers on GitHub split into two kinds:
| Repository | Stars, last push | What it does | Needs |
|---|---|---|---|
| eat-pray-ai/yutu | 723, Nov 15, 2026 | CLI and MCP server over the Data API: videos, playlists, comments, captions, channels, uploads | OAuth client and token |
| ZubeidHendricks/youtube-mcp-server | 598, Aug 8, 2026 | 10 tools: video and channel lookup and search, playlists, transcripts | API key |
| kimtaeyoon83/mcp-server-youtube-transcript | 604, Jul 21, 2026 | get_transcript by URL or ID |
Nothing (reads the website) |
| anaisbetts/mcp-youtube | 553, Aug 16, 2026 | Subtitles through a local yt-dlp | yt-dlp installed |
| jkawamoto/mcp-youtube-transcript | 498, Nov 14, 2026 | Transcripts, timed segments, languages, video info, paged for long videos | Nothing (reads the website) |
| kirbah/mcp-youtube | 34, Nov 13, 2026 | Token-trimmed video, channel, comment and search tools | API key |
Servers that use your API key spend your quota, and their search tools draw on the 100-a-day search bucket. The transcript tools in every server above, including the transcript tool in the API-key servers, read YouTube’s website, so the terms in the transcripts section apply to them.
Claude Code
claude mcp add youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- npx -y zubeid-youtube-mcp-serverClaude Desktop and Cursor
Claude Desktop reads claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS); Cursor reads ~/.cursor/mcp.json or .cursor/mcp.json in a project. Both take the same entry:
{ "mcpServers": { "youtube": { "command": "npx", "args": ["-y", "zubeid-youtube-mcp-server"], "env": { "YOUTUBE_API_KEY": "YOUR_API_KEY" } } }}Restart the client after saving. For write access to your own channel, yutu authenticates once with yutu auth --credential client_secret.json and then registers itself in Claude Code with yutu mcp setup --agents claude.
ChatGPT
ChatGPT connects only to remote servers. OpenAI’s developer mode guide adds one under ChatGPT Plugins, Add custom MCP server, with a server URL over SSE or streaming HTTP and either OAuth or no authentication. None of the GitHub servers above is hosted, so using one in ChatGPT means running it behind a public HTTPS URL yourself. OpenAI lists only OAuth or no authentication, so a self-hosted server has to hold the YouTube key on its own side.
How Claude and ChatGPT handle YouTube links
Neither assistant documents watching a YouTube video from a pasted link in an ordinary chat.
- Claude. Anthropic’s web fetch tool returns “Content type not supported (only text, HTML, and PDF)” for anything else and does not support pages rendered with JavaScript. A YouTube link gives Claude the watch page’s text at most, not the audio or the captions. Reading what was said needs a transcript you paste in or an MCP server.
- ChatGPT. OpenAI’s changelog entry of July 30, 2026 says you can “Ask questions about any YouTube video in the Chrome extension”. That is the only YouTube feature OpenAI documents; it lives in the browser extension, not in the API or a regular chat.
YouTube API Services Terms and Developer Policies
Using the API means accepting the YouTube API Services Terms of Service and the Developer Policies. The rules that catch data and AI projects:
- 30-day storage. Data read without a user’s authorization may be stored only as long as needed and never more than 30 calendar days, then deleted or refreshed. Statistics such as a channel’s subscriber count read that way must not be kept beyond 30 days. Since June 1, 2026, audited developers whose analytics use case is accepted may keep some statistics longer.
- No derived metrics. Clients must not “access or use API Data to create new or derived data or metrics”, such as a score built from likes and views, unless an audited developer has applied for and received that permission under the May 2026 policy.
- No aggregation of API data across channels except for one content owner’s channels, and none to gain insight into YouTube’s business.
- No scraping and no copies of video without YouTube’s prior written approval.
- A privacy policy is required for every API client, and data tied to a user who revokes access must be deleted within 30 calendar days.
- Changes take effect no sooner than 30 days after Google posts them, except for new features or legal reasons.
Choosing a route
- Public video, channel and playlist data: the Data API with a restricted API key. List channels through the uploads playlist, not search.
- Discovery by keyword:
search.list, budgeted at 100 calls a day, with results stored no longer than 30 days. - Your own channel, uploads, comments and captions: OAuth 2.0 with the narrowest scope.
- Transcripts of your own videos:
captions.download(200 units each). - Transcripts of other people’s videos: no official route. Open-source libraries work by reading the website against YouTube’s terms; check the terms before you build on them.
- An AI assistant that reads YouTube: a self-run MCP server with your own key in Claude Code, Claude Desktop or Cursor.
- Cited research that includes videos: Hyperresearch reads YouTube video titles, channels, dates and descriptions as one of its 120+ data sources and cites a video by its page; it does not read transcripts.
For other platforms, see the X API guide, the Reddit MCP server guide and MCP servers for research data. For what Claude’s own browsing can and cannot read, see Claude web search.
Sources
- Quota Calculator: https://developers.google.com/youtube/v3/determine_quota_cost
- YouTube Data API Overview (Getting Started): https://developers.google.com/youtube/v3/getting-started
- Quota and Compliance Audits: https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits
- YouTube API Services Audit and Quota Extension Form: https://support.google.com/youtube/contact/yt_api_form
- Data API Revision History: https://developers.google.com/youtube/v3/revision_history
- YouTube API Services Terms revision history: https://developers.google.com/youtube/terms/revision-history
- Implement authorization (API keys and OAuth 2.0): https://developers.google.com/youtube/v3/guides/authentication
- Python Quickstart: https://developers.google.com/youtube/v3/quickstart/python
- Reference pages: https://developers.google.com/youtube/v3/docs/search/list, /videos/list, /videos/batchGetStats, /channels/list, /playlistItems/list, /commentThreads/list, /captions/list, /captions/download
- Errors reference: https://developers.google.com/youtube/v3/docs/errors
- Google captions sample: https://github.com/youtube/api-samples/blob/master/python/captions.py
- Google Cloud, Manage API keys: https://cloud.google.com/docs/authentication/api-keys
- Google Cloud, Use API keys (x-goog-api-key header): https://cloud.google.com/docs/authentication/api-keys-use
- Google Cloud MCP servers, supported products: https://docs.cloud.google.com/mcp/supported-products
- YouTube API Services Terms of Service: https://developers.google.com/youtube/terms/api-services-terms-of-service
- YouTube API Services Developer Policies: https://developers.google.com/youtube/terms/developer-policies
- YouTube Terms of Service (dated December 15, 2023): https://www.youtube.com/static?template=terms
- Official MCP registry search API: https://registry.modelcontextprotocol.io/v0/servers?search=youtube
- jdepoix/youtube-transcript-api README: https://github.com/jdepoix/youtube-transcript-api
- Anthropic web fetch tool: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
- OpenAI developer mode (custom MCP servers): https://developers.openai.com/api/docs/guides/developer-mode
- ChatGPT changelog, July 30, 2026: https://learn.chatgpt.com/docs/changelog
- Cursor MCP docs: https://cursor.com/docs/context/mcp
