A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The YouTube API is how an app or AI agent works with a YouTube channel: searching for videos, reading channel and video statistics, uploading and updating videos, managing playlists, and posting or moderating comments. Access comes through an API key for public reads, or an OAuth 2.0 access token whose scopes decide what the caller can read or change, and a token is limited to the channel of the account that granted it. Use is metered in quota units rather than request count, so reads are cheap while searches and writes cost far more.
How an app or AI agent connects to YouTube determines what it can reach. Most reads of public data need only an API key, while anything tied to a channel or any write needs an OAuth 2.0 access token, and the scopes on that token set the boundary.
The YouTube Data API v3 answers at https://www.googleapis.com/youtube/v3. Public reads can use a simple API key, while channel-bound reads and all writes require an OAuth 2.0 access token.
The Data API has no webhooks. To learn of new uploads, an app subscribes to a channel's Atom feed through Google's PubSubHubbub hub, which posts a notification when that channel publishes or updates a video.
Google publishes official client libraries for the Data API in languages such as Python, JavaScript, Java, Go, and .NET, which handle authentication, request signing, and pagination.
An API key authenticates the application, not a user, and can read public data such as public videos, channels, and playlists. It cannot touch anything that belongs to a specific user or make any write.
OAuth 2.0 grants an access token on behalf of a Google account that owns a YouTube channel, with the scopes the user approves. It is required for any private read and every write, and a Google account with no linked channel is rejected.
The YouTube Data API is split into resources an agent can act on, such as videos, channels, playlists, comments, subscriptions, and captions. Each resource has its own methods and its own scope, and some grant access to far more than others.
Search across videos, channels, and playlists by keyword, and filter by date, region, type, and more.
List video details and statistics, upload a video, update its metadata, rate it, read the caller's rating, and delete it.
Read a channel's details and statistics, and update its branding and settings.
List, create, update, and delete playlists on a channel.
List the videos in a playlist, add a video to one, and update or remove an entry.
List comment threads on a video, read replies, post a top-level comment or a reply, update one, and set its moderation status.
List a channel's subscriptions, subscribe to a channel, and unsubscribe.
List and upload caption tracks for a video, and set a custom thumbnail.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SearchSearch across videos, channels, and playlists by keyword, and filter by date, region, type, and more.1 | ||||||
| GET | /youtube/v3/search | Search for videos, channels, and playlists matching a query, with filters for date, region, type, and order. | read | youtube.readonly | Current | |
Searching public content needs only an API key; no OAuth scope is required unless filtering by the caller's own resources. When a token is used, the read-only scope is https://www.googleapis.com/auth/youtube.readonly. This is the costliest read at 100 quota units per call. Acts onsearch result Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
VideosList video details and statistics, upload a video, update its metadata, rate it, read the caller's rating, and delete it.6 | ||||||
| GET | /youtube/v3/videos | Retrieve a list of videos by id, or charts such as the most popular videos, with details, statistics, and status. | read | youtube.readonly | Current | |
Reading public videos needs only an API key; the rating and fileDetails parts need the token owner's authorization. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onvideo Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/videos | Upload a video to a channel and set its metadata. | write | youtube.upload | Current | |
Needs the upload scope https://www.googleapis.com/auth/youtube.upload (or the broader youtube or youtube.force-ssl). Uploads draw on a separate daily allowance of 100 calls rather than the shared 10,000-unit pool; each upload counts as roughly 1 unit against that bucket. Acts onvideo Permission (capability) youtube.uploadVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit (100 uploads per day) SourceOfficial documentation ↗ | ||||||
| PUT | /youtube/v3/videos | Update a video's metadata, such as its title, description, tags, category, and privacy status. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl). Any unset writable property in the request is reset, so the full object should be sent. Acts onvideo Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/videos/rate | Set the caller's like, dislike, or no rating on a video. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl). Acts as the authenticated user. Acts onvideo rating Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| GET | /youtube/v3/videos/getRating | Read the rating the caller has given to one or more videos. | read | youtube.readonly | Current | |
Needs the caller's authorization. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onvideo rating Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| DELETE | /youtube/v3/videos | Delete a video owned by the authenticated channel. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl). The deletion is permanent. Acts onvideo Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
ChannelsRead a channel's details and statistics, and update its branding and settings.2 | ||||||
| GET | /youtube/v3/channels | Retrieve channel details and statistics by id, username, handle, or the authenticated user's own channel. | read | youtube.readonly | Current | |
Reading public channels needs only an API key; the mine parameter and private parts need authorization. The forHandle parameter, added January 2024, looks a channel up by its handle. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onchannel Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| PUT | /youtube/v3/channels | Update a channel's branding settings, including its localizations and other channel metadata. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtubepartner). Only a subset of channel properties can be set this way. Acts onchannel Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
PlaylistsList, create, update, and delete playlists on a channel.4 | ||||||
| GET | /youtube/v3/playlists | Retrieve playlists by id, by channel, or the authenticated user's own playlists. | read | youtube.readonly | Current | |
Reading public playlists needs only an API key; the mine parameter needs authorization. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onplaylist Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/playlists | Create a playlist on the authenticated channel. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl, or youtubepartner). Acts onplaylist Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| PUT | /youtube/v3/playlists | Update a playlist's title, description, and privacy status. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl, or youtubepartner). Any unset writable property is reset. Acts onplaylist Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /youtube/v3/playlists | Delete a playlist owned by the authenticated channel. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl, or youtubepartner). Acts onplaylist Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
Playlist itemsList the videos in a playlist, add a video to one, and update or remove an entry.2 | ||||||
| GET | /youtube/v3/playlistItems | List the videos contained in a playlist. | read | youtube.readonly | Current | |
Reading items in a public playlist needs only an API key. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onplaylist item Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/playlistItems | Add a video to a playlist. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl, or youtubepartner). Acts onplaylist item Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
CommentsList comment threads on a video, read replies, post a top-level comment or a reply, update one, and set its moderation status.3 | ||||||
| GET | /youtube/v3/commentThreads | List comment threads on a video or channel, each with its top-level comment and a sample of replies. | read | youtube.force-ssl | Current | |
Public comment threads can be read with an API key. When a token is used, the force-ssl scope is https://www.googleapis.com/auth/youtube.force-ssl. Acts oncomment thread Permission (capability) youtube.force-sslVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/comments | Post a reply to an existing comment thread. | write | youtube.force-ssl | Current | |
Needs the force-ssl scope https://www.googleapis.com/auth/youtube.force-ssl, which is the only scope that grants comment writes. To start a new top-level comment thread, use commentThreads.insert instead. Acts oncomment Permission (capability) youtube.force-sslVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/comments/setModerationStatus | Set the moderation status of one or more comments, such as publishing held comments or rejecting them. | write | youtube.force-ssl | Current | |
Needs the force-ssl scope https://www.googleapis.com/auth/youtube.force-ssl. The caller must own the video or channel the comments are on. Acts oncomment Permission (capability) youtube.force-sslVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
SubscriptionsList a channel's subscriptions, subscribe to a channel, and unsubscribe.2 | ||||||
| GET | /youtube/v3/subscriptions | List the subscriptions of the authenticated user or a specified channel. | read | youtube.readonly | Current | |
Needs the caller's authorization to read their own subscriptions. Read-only scope: https://www.googleapis.com/auth/youtube.readonly. Acts onsubscription Permission (capability) youtube.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 quota unit SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/subscriptions | Subscribe the authenticated channel to another channel. | write | youtube | Current | |
Needs the manage scope https://www.googleapis.com/auth/youtube (or youtube.force-ssl, or youtubepartner). Acts onsubscription Permission (capability) youtubeVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
Captions & thumbnailsList and upload caption tracks for a video, and set a custom thumbnail.3 | ||||||
| GET | /youtube/v3/captions | List the caption tracks associated with a video. | read | youtube.force-ssl | Current | |
Needs the force-ssl scope https://www.googleapis.com/auth/youtube.force-ssl (or youtubepartner), and the caller must own the video. Listing captions costs 50 units, more than a typical read. Acts oncaption Permission (capability) youtube.force-sslVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/captions | Upload a caption track for a video. | write | youtube.force-ssl | Current | |
Needs the force-ssl scope https://www.googleapis.com/auth/youtube.force-ssl (or youtubepartner). Since March 2024 the sync parameter is deprecated, so caption files must carry their own timing. Acts oncaption Permission (capability) youtube.force-sslVersionAvailable since the API’s base version Webhook eventNone Rate limit400 quota units SourceOfficial documentation ↗ | ||||||
| POST | /youtube/v3/thumbnails/set | Upload a custom thumbnail image and set it for a video. | write | youtube.upload | Current | |
Needs the upload scope https://www.googleapis.com/auth/youtube.upload (or youtube, youtube.force-ssl, or youtubepartner). Custom thumbnails require the channel to be verified. Acts onthumbnail Permission (capability) youtube.uploadVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
The YouTube Data API has no webhooks. To be notified when a channel uploads a new video, an app or AI agent subscribes to that channel's feed through PubSubHubbub, a separate push service, rather than polling the API.
| Event | What it signals | Triggered by |
|---|
YouTube limits use by quota units rather than by request count. Every call spends units from a daily allowance, with reads costing little and writes and searches costing far more, so the model rewards reading and rations writing.
YouTube governs the Data API by quota units, not by a simple request count. Every project starts with a default allowance of 10,000 units per day, shared across most endpoints and reset at midnight Pacific time. The cost depends on the method: a read that retrieves a list of resources such as videos, channels, or playlists usually costs 1 unit, a write that creates, updates, or deletes a resource usually costs 50 units, and a search costs 100 units. Some methods cost more, such as listing or uploading captions. Two methods sit in their own daily buckets rather than the shared pool: search.list is capped at 100 calls per day and video uploads at 100 per day. Each endpoint's cost is shown on its row. The error code quotaExceeded signals the allowance is spent, and a higher quota can be requested from Google.
List methods return a fixed page of results with a nextPageToken (and where relevant a prevPageToken) in the response. The next page is fetched by passing that token back in the pageToken parameter, repeating until no token is returned. The maxResults parameter sets the page size, accepting 0 to 50 for most methods, with a default of 5. Result paging cannot jump to an arbitrary offset.
Requests and responses are JSON. The part parameter controls which sections of a resource are returned, and trimming it lowers the response size. Media uploads such as videos and captions are sent as separate multipart or resumable uploads, with the maximum video file size set by the channel's upload limits rather than the API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | badRequest | The request is malformed: an invalid parameter value, a missing required parameter, or two parameters that cannot be combined. Specific reasons include missingRequiredParameter and incompatibleParameters. | Read the reason in the error body, correct the named parameter, and resend. |
| 401 | authorizationRequired | The request uses a parameter that needs authorization, such as mine, but no valid OAuth credentials were sent. A related youtubeSignupRequired means the Google account has no linked YouTube channel. | Send a valid OAuth 2.0 access token for an account that owns a YouTube channel. |
| 403 | forbidden | The request is authenticated but not permitted: the token lacks the scope the method needs, or the caller does not own the resource it is acting on. | Grant the missing scope, or act only on resources the authenticated channel owns. |
| 403 | quotaExceeded | The daily quota allowance has been spent. Because writes and searches cost far more than reads, a project can hit this with relatively few calls. | Wait for the daily reset at midnight Pacific time, cut quota use, or request a higher quota allowance. |
| 404 | notFound | The video, channel, playlist, or other resource named in the request does not exist or cannot be seen by the caller. | Confirm the id is correct and that the resource is public or owned by the authenticated user. |
| 429 | tooManyRequests | Too many requests were sent in a short window, separate from the daily quota. An example is uploadRateLimitExceeded when uploads or thumbnail sets come too fast. | Back off and retry after a delay, spreading requests out over time. |
The YouTube Data API is on version 3. There is no dated version string to pin, so the API is continuously updated and notable changes ship through the revision history.
Version 3 is the current YouTube Data API. It is not pinned by a dated version string; instead it is continuously updated, and notable changes ship through the dated revision history. The entries below are the most recent notable changes, newest first.
A new videos.batchGetStats method retrieves video statistics from a dedicated daily quota bucket, separate from the shared 10,000-unit pool.
search.list and videos.insert moved to their own separate daily quota buckets as part of a more granular quota model, rather than drawing on the shared pool.
The quota cost of a video upload through videos.insert was reduced substantially, making programmatic uploads far cheaper against the daily allowance.
Channel discussions were discontinued, ending the activities.insert method for that use.
The sync parameter for captions.insert and captions.update was deprecated, so uploaded caption files must now carry their own timing information.
A forHandle parameter was added to channels.list, letting a channel be looked up by its YouTube handle.
An integration tracks changes through the dated revision history rather than pinning a version.
YouTube Data API revision history ↗Bollard AI sits between a team's AI agents and YouTube. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.