# Table of Contents - [API Reference  |  YouTube Data API  |  Google for Developers](#api-reference-youtube-data-api-google-for-developers) - [Captions: insert  |  YouTube Data API  |  Google for Developers](#captions-insert-youtube-data-api-google-for-developers) - [Channels: list  |  YouTube Data API  |  Google for Developers](#channels-list-youtube-data-api-google-for-developers) - [I18nLanguages: list  |  YouTube Data API  |  Google for Developers](#i18nlanguages-list-youtube-data-api-google-for-developers) - [CommentThreads: insert  |  YouTube Data API  |  Google for Developers](#commentthreads-insert-youtube-data-api-google-for-developers) - [Comments: delete  |  YouTube Data API  |  Google for Developers](#comments-delete-youtube-data-api-google-for-developers) - [Members  |  YouTube Data API  |  Google for Developers](#members-youtube-data-api-google-for-developers) - [I18nRegions  |  YouTube Data API  |  Google for Developers](#i18nregions-youtube-data-api-google-for-developers) - [PlaylistImages: list  |  YouTube Data API  |  Google for Developers](#playlistimages-list-youtube-data-api-google-for-developers) - [Members: list  |  YouTube Data API  |  Google for Developers](#members-list-youtube-data-api-google-for-developers) - [CommentThreads: list  |  YouTube Data API  |  Google for Developers](#commentthreads-list-youtube-data-api-google-for-developers) - [Subscriptions: list  |  YouTube Data API  |  Google for Developers](#subscriptions-list-youtube-data-api-google-for-developers) - [MembershipsLevels: list  |  YouTube Data API  |  Google for Developers](#membershipslevels-list-youtube-data-api-google-for-developers) - [PlaylistItems: delete  |  YouTube Data API  |  Google for Developers](#playlistitems-delete-youtube-data-api-google-for-developers) - [Thumbnails: set  |  YouTube Data API  |  Google for Developers](#thumbnails-set-youtube-data-api-google-for-developers) - [Search  |  YouTube Data API  |  Google for Developers](#search-youtube-data-api-google-for-developers) - [I18nLanguages  |  YouTube Data API  |  Google for Developers](#i18nlanguages-youtube-data-api-google-for-developers) - [PlaylistItems: insert  |  YouTube Data API  |  Google for Developers](#playlistitems-insert-youtube-data-api-google-for-developers) - [Subscriptions  |  YouTube Data API  |  Google for Developers](#subscriptions-youtube-data-api-google-for-developers) - [VideoCategories: list  |  YouTube Data API  |  Google for Developers](#videocategories-list-youtube-data-api-google-for-developers) - [Playlists  |  YouTube Data API  |  Google for Developers](#playlists-youtube-data-api-google-for-developers) - [Playlists: delete  |  YouTube Data API  |  Google for Developers](#playlists-delete-youtube-data-api-google-for-developers) - [PlaylistItems: list  |  YouTube Data API  |  Google for Developers](#playlistitems-list-youtube-data-api-google-for-developers) - [VideoAbuseReportReasons: list  |  YouTube Data API  |  Google for Developers](#videoabusereportreasons-list-youtube-data-api-google-for-developers) - [PlaylistImages: delete  |  YouTube Data API  |  Google for Developers](#playlistimages-delete-youtube-data-api-google-for-developers) - [MembershipsLevels  |  YouTube Data API  |  Google for Developers](#membershipslevels-youtube-data-api-google-for-developers) - [PlaylistImages: insert  |  YouTube Data API  |  Google for Developers](#playlistimages-insert-youtube-data-api-google-for-developers) - [PlaylistImages  |  YouTube Data API  |  Google for Developers](#playlistimages-youtube-data-api-google-for-developers) - [Google APIs - Global domain errors  |  YouTube Data API  |  Google for Developers](#google-apis-global-domain-errors-youtube-data-api-google-for-developers) - [Videos: getRating  |  YouTube Data API  |  Google for Developers](#videos-getrating-youtube-data-api-google-for-developers) - [Videos: rate  |  YouTube Data API  |  Google for Developers](#videos-rate-youtube-data-api-google-for-developers) - [Videos: reportAbuse  |  YouTube Data API  |  Google for Developers](#videos-reportabuse-youtube-data-api-google-for-developers) - [Watermarks: set  |  YouTube Data API  |  Google for Developers](#watermarks-set-youtube-data-api-google-for-developers) - [Watermarks: unset  |  YouTube Data API  |  Google for Developers](#watermarks-unset-youtube-data-api-google-for-developers) - [Subscriptions: insert  |  YouTube Data API  |  Google for Developers](#subscriptions-insert-youtube-data-api-google-for-developers) - [PlaylistItems: update  |  YouTube Data API  |  Google for Developers](#playlistitems-update-youtube-data-api-google-for-developers) - [ChannelSections: update  |  YouTube Data API  |  Google for Developers](#channelsections-update-youtube-data-api-google-for-developers) - [ChannelSections: list  |  YouTube Data API  |  Google for Developers](#channelsections-list-youtube-data-api-google-for-developers) - [PlaylistImages: update  |  YouTube Data API  |  Google for Developers](#playlistimages-update-youtube-data-api-google-for-developers) - [I18nRegions: list  |  YouTube Data API  |  Google for Developers](#i18nregions-list-youtube-data-api-google-for-developers) - [Thumbnails  |  YouTube Data API  |  Google for Developers](#thumbnails-youtube-data-api-google-for-developers) - [Playlists: insert  |  YouTube Data API  |  Google for Developers](#playlists-insert-youtube-data-api-google-for-developers) - [Videos: list  |  YouTube Data API  |  Google for Developers](#videos-list-youtube-data-api-google-for-developers) - [Videos: delete  |  YouTube Data API  |  Google for Developers](#videos-delete-youtube-data-api-google-for-developers) - [Playlists: update  |  YouTube Data API  |  Google for Developers](#playlists-update-youtube-data-api-google-for-developers) - [VideoCategories  |  YouTube Data API  |  Google for Developers](#videocategories-youtube-data-api-google-for-developers) - [Subscriptions: delete  |  YouTube Data API  |  Google for Developers](#subscriptions-delete-youtube-data-api-google-for-developers) - [VideoAbuseReportReasons  |  YouTube Data API  |  Google for Developers](#videoabusereportreasons-youtube-data-api-google-for-developers) - [Search: list  |  YouTube Data API  |  Google for Developers](#search-list-youtube-data-api-google-for-developers) - [Playlists: list  |  YouTube Data API  |  Google for Developers](#playlists-list-youtube-data-api-google-for-developers) - [Videos: update  |  YouTube Data API  |  Google for Developers](#videos-update-youtube-data-api-google-for-developers) - [Watermarks  |  YouTube Data API  |  Google for Developers](#watermarks-youtube-data-api-google-for-developers) - [Videos: insert  |  YouTube Data API  |  Google for Developers](#videos-insert-youtube-data-api-google-for-developers) - [ChannelBanners: insert  |  YouTube Data API  |  Google for Developers](#channelbanners-insert-youtube-data-api-google-for-developers) - [PlaylistItems  |  YouTube Data API  |  Google for Developers](#playlistitems-youtube-data-api-google-for-developers) - [CommentThreads  |  YouTube Data API  |  Google for Developers](#commentthreads-youtube-data-api-google-for-developers) - [YouTube Data API - Errors  |  Google for Developers](#youtube-data-api-errors-google-for-developers) - [Videos  |  YouTube Data API  |  Google for Developers](#videos-youtube-data-api-google-for-developers) - [API Reference  |  YouTube Data API  |  Google for Developers](#api-reference-youtube-data-api-google-for-developers) --- # API Reference  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * [English](https://developers.google.com/youtube/v3/docs) * [Deutsch](https://developers.google.com/youtube/v3/docs?hl=de) * [Español](https://developers.google.com/youtube/v3/docs?hl=es) * [Español – América Latina](https://developers.google.com/youtube/v3/docs?hl=es-419) * [Français](https://developers.google.com/youtube/v3/docs?hl=fr) * [Indonesia](https://developers.google.com/youtube/v3/docs?hl=id) * [Italiano](https://developers.google.com/youtube/v3/docs?hl=it) * [Polski](https://developers.google.com/youtube/v3/docs?hl=pl) * [Português – Brasil](https://developers.google.com/youtube/v3/docs?hl=pt-br) * [Tiếng Việt](https://developers.google.com/youtube/v3/docs?hl=vi) * [Türkçe](https://developers.google.com/youtube/v3/docs?hl=tr) * [Русский](https://developers.google.com/youtube/v3/docs?hl=ru) * [עברית](https://developers.google.com/youtube/v3/docs?hl=he) * [العربيّة](https://developers.google.com/youtube/v3/docs?hl=ar) * [فارسی](https://developers.google.com/youtube/v3/docs?hl=fa) * [हिंदी](https://developers.google.com/youtube/v3/docs?hl=hi) * [বাংলা](https://developers.google.com/youtube/v3/docs?hl=bn) * [ภาษาไทย](https://developers.google.com/youtube/v3/docs?hl=th) * [中文 – 简体](https://developers.google.com/youtube/v3/docs?hl=zh-cn) * [中文 – 繁體](https://developers.google.com/youtube/v3/docs?hl=zh-tw) * [日本語](https://developers.google.com/youtube/v3/docs?hl=ja) * [한국어](https://developers.google.com/youtube/v3/docs?hl=ko) [Sign in](https://developers.google.com/_d/signin?continue=https%3A%2F%2Fdevelopers.google.com%2Fyoutube%2Fv3%2Fdocs&prompt=select_account) * On this page * [Call the API](https://developers.google.com/youtube/v3/docs#call-the-api) * [Resource types](https://developers.google.com/youtube/v3/docs#resource-types) * [Activities](https://developers.google.com/youtube/v3/docs#Activities) * [Captions](https://developers.google.com/youtube/v3/docs#Captions) * [ChannelBanners](https://developers.google.com/youtube/v3/docs#ChannelBanners) * [ChannelSections](https://developers.google.com/youtube/v3/docs#ChannelSections) * [Channels](https://developers.google.com/youtube/v3/docs#Channels) * [CommentThreads](https://developers.google.com/youtube/v3/docs#CommentThreads) * [Comments](https://developers.google.com/youtube/v3/docs#Comments) * [I18nLanguages](https://developers.google.com/youtube/v3/docs#I18nLanguages) * [I18nRegions](https://developers.google.com/youtube/v3/docs#I18nRegions) * [Members](https://developers.google.com/youtube/v3/docs#Members) * [MembershipsLevels](https://developers.google.com/youtube/v3/docs#MembershipsLevels) * [PlaylistItems](https://developers.google.com/youtube/v3/docs#PlaylistItems) * [Playlists](https://developers.google.com/youtube/v3/docs#Playlists) * [Search](https://developers.google.com/youtube/v3/docs#Search) * [Subscriptions](https://developers.google.com/youtube/v3/docs#Subscriptions) * [Thumbnails](https://developers.google.com/youtube/v3/docs#Thumbnails) * [VideoAbuseReportReasons](https://developers.google.com/youtube/v3/docs#VideoAbuseReportReasons) * [VideoCategories](https://developers.google.com/youtube/v3/docs#VideoCategories) * [Videos](https://developers.google.com/youtube/v3/docs#Videos) * [Watermarks](https://developers.google.com/youtube/v3/docs#Watermarks) * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Was this helpful? API Reference Stay organized with collections Save and categorize content based on your preferences. ==================================================================================================== * On this page * [Call the API](https://developers.google.com/youtube/v3/docs#call-the-api) * [Resource types](https://developers.google.com/youtube/v3/docs#resource-types) * [Activities](https://developers.google.com/youtube/v3/docs#Activities) * [Captions](https://developers.google.com/youtube/v3/docs#Captions) * [ChannelBanners](https://developers.google.com/youtube/v3/docs#ChannelBanners) * [ChannelSections](https://developers.google.com/youtube/v3/docs#ChannelSections) * [Channels](https://developers.google.com/youtube/v3/docs#Channels) * [CommentThreads](https://developers.google.com/youtube/v3/docs#CommentThreads) * [Comments](https://developers.google.com/youtube/v3/docs#Comments) * [I18nLanguages](https://developers.google.com/youtube/v3/docs#I18nLanguages) * [I18nRegions](https://developers.google.com/youtube/v3/docs#I18nRegions) * [Members](https://developers.google.com/youtube/v3/docs#Members) * [MembershipsLevels](https://developers.google.com/youtube/v3/docs#MembershipsLevels) * [PlaylistItems](https://developers.google.com/youtube/v3/docs#PlaylistItems) * [Playlists](https://developers.google.com/youtube/v3/docs#Playlists) * [Search](https://developers.google.com/youtube/v3/docs#Search) * [Subscriptions](https://developers.google.com/youtube/v3/docs#Subscriptions) * [Thumbnails](https://developers.google.com/youtube/v3/docs#Thumbnails) * [VideoAbuseReportReasons](https://developers.google.com/youtube/v3/docs#VideoAbuseReportReasons) * [VideoCategories](https://developers.google.com/youtube/v3/docs#VideoCategories) * [Videos](https://developers.google.com/youtube/v3/docs#Videos) * [Watermarks](https://developers.google.com/youtube/v3/docs#Watermarks) ![Spark icon](https://developers.google.com/_static/images/icons/spark.svg) Page Summary ------------ outlined\_flag * The YouTube Data API allows integration of YouTube features into external applications, with resources like videos and playlists represented as JSON objects. * Authentication for the API requires either an API key or an OAuth 2.0 token, with authorization tokens being mandatory for operations that modify data or access private user information. * The API uses standard HTTP methods such as `LIST`, `POST`, `DELETE`, and `PUT` to manage various resource types, including captions, playlists, channels, and videos. * The API offers a wide array of resources and methods for channels, such as managing channel banners, sections, and memberships, alongside actions related to comments, subscriptions, and user activities. * The API also allows you to retrieve different data sets related to the application, such as getting supported regions, supported languages, and reasons for video abuse reports. The YouTube Data API lets you incorporate functions normally executed on the YouTube website into your own website or application. The following sections identify the different types of resources that you can retrieve using the API. The API also supports methods to insert, update, or delete many of these resources. This reference guide explains how to use the API to perform all of these operations. The guide is organized by resource type. A resource represents a type of item that comprises part of the YouTube experience, such as a video, a playlist, or a subscription. For each resource type, the guide lists one or more data representations, and resources are represented as JSON objects. The guide also lists one or more supported methods (`LIST`, `POST`, `DELETE`, etc.) for each resource type and explains how to use those methods in your application. Call the API ------------ The following requirements apply to YouTube Data API requests: 1. Every request must either specify an API key (with the `key` parameter) or provide an OAuth 2.0 token. Your API key is available in the [Developer Console's](https://console.developers.google.com/) **API Access** pane for your project. 2. You **must** send an authorization token for every insert, update, and delete request. You must also send an authorization token for any request that retrieves the authenticated user's private data. In addition, some API methods for retrieving resources may support parameters that require authorization or may contain additional metadata when requests are authorized. For example, a request to retrieve a user's uploaded videos may also contain private videos if the request is authorized by that specific user. 3. The API supports the OAuth 2.0 authentication protocol. You can provide an OAuth 2.0 token in either of the following ways: * Use the `access_token` query parameter like this: `?access_token=``oauth2-token` * Use the HTTP `Authorization` header like this: `Authorization: Bearer` `oauth2-token` Complete instructions for implementing OAuth 2.0 authentication in your application can be found in the [authentication guide](https://developers.google.com/youtube/v3/guides/authentication) . Resource types -------------- ### Activities An `**activity**` resource contains information about an action that a particular channel, or user, has taken on YouTube. The actions reported in activity feeds include rating a video, sharing a video, marking a video as a favorite, uploading a video, and so forth. Each `activity` resource identifies the type of action, the channel associated with the action, and the resource(s) associated with the action, such as the video that was rated or uploaded. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/activities#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/activities#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/activities/list) ` | `GET /activities` | Returns a list of channel activity events that match the request criteria. For example, you can retrieve events associated with a particular channel or with the user's own channel. | ### Captions A `**caption**` resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/captions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/captions#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[delete](https://developers.google.com/youtube/v3/docs/captions/delete) ` | `DELETE /captions` | Deletes the specified caption track. | | `[download](https://developers.google.com/youtube/v3/docs/captions/download) ` | `GET /captions/id` | Downloads a caption track. The caption track is returned in its original format unless the request specifies a value for the `tfmt` parameter and in its original language unless the request specifies a value for the `tlang` parameter. | | `[insert](https://developers.google.com/youtube/v3/docs/captions/insert) ` | `POST /captions` | Uploads a caption track. | | `[list](https://developers.google.com/youtube/v3/docs/captions/list) ` | `GET /captions` | Returns a list of caption tracks that are associated with a specified video. The API response does not contain the actual captions and that the `[captions.download](https://developers.google.com/youtube/v3/docs/captions/download) ` method provides the ability to retrieve a caption track. | | `[update](https://developers.google.com/youtube/v3/docs/captions/update) ` | `PUT /captions` | Updates a caption track. When updating a caption track, you can change the track's [draft status](https://developers.google.com/youtube/v3/docs/captions#snippet.isDraft)
, upload a new caption file for the track, or both. | ### ChannelBanners A `channelBanner` resource contains the URL that you would use to set a newly uploaded image as the banner image for a channel. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/channelBanners#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channelBanners#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[insert](https://developers.google.com/youtube/v3/docs/channelBanners/insert) ` | `POST /channelBanners/insert` | Uploads a channel banner image to YouTube. This method represents the first two steps in a three-step process to update the banner image for a channel:

1. Call the `channelBanners.insert` method to upload the binary image data to YouTube. The image must have a 16:9 aspect ratio and be at least 2048x1152 pixels. We recommend uploading a 2560px by 1440px image.
2. Extract the `url` property's value from the response that the API returns for step 1.
3. Call the `[channels.update](https://developers.google.com/youtube/v3/docs/channels/update) ` method to update the channel's branding settings. Set the `[brandingSettings.image.bannerExternalUrl](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.image.bannerExternalUrl) ` property's value to the URL obtained in step 2. | ### ChannelSections A `**channelSection**` resource contains information about a set of videos that a channel has chosen to feature. For example, a section could feature a channel's latest uploads, most popular uploads, or videos from one or more playlists. A channel's sections are only visible if the channel displays content in a browse view (rather than a feed view). To enable a channel to display content in a browse view, set the `[brandingSettings.channel.showBrowseView](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.showBrowseView) ` property to `true` for the specified channel. A channel can create a maximum of 10 shelves. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/channelSections#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channelSections#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[delete](https://developers.google.com/youtube/v3/docs/channelSections/delete) ` | `DELETE /channelSections` | Deletes a channel section. | | `[insert](https://developers.google.com/youtube/v3/docs/channelSections/insert) ` | `POST /channelSections` | Adds a channel section to the authenticated user's channel. A channel can create a maximum of 10 shelves. | | `[list](https://developers.google.com/youtube/v3/docs/channelSections/list) ` | `GET /channelSections` | Returns a list of `channelSection` resources that match the API request criteria. | | `[update](https://developers.google.com/youtube/v3/docs/channelSections/update) ` | `PUT /channelSections` | Updates a channel section. | ### Channels A `**channel**` resource contains information about a YouTube channel. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/channels#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channels#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/channels/list) ` | `GET /channels` | Returns a collection of zero or more `**channel**` resources that match the request criteria. | | `[update](https://developers.google.com/youtube/v3/docs/channels/update) ` | `PUT /channels` | Updates a channel's metadata. This method only supports updates to the `channel` resource's `brandingSettings` and `invideoPromotion` objects and their child properties. | ### CommentThreads A `**commentThread**` resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. A `commentThread` resource can represent comments about either a video or a channel. Both the top-level comment and the replies are actually `[comment](https://developers.google.com/youtube/v3/docs/comments) ` resources nested inside the `commentThread` resource. The `commentThread` resource does not necessarily contain all replies to a comment, and you need to use the `[comments.list](https://developers.google.com/youtube/v3/docs/comments/list) ` method if you want to retrieve all replies for a particular comment. Also, some comments don't have replies. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/commentThreads#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/commentThreads#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/commentThreads/list) ` | `GET /commentThreads` | Returns a list of comment threads that match the API request parameters. | | `[insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) ` | `POST /commentThreads` | Creates a new top-level comment. To add a reply to an existing comment, use the `[comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert) ` method instead. | ### Comments A `**comment**` resource contains information about a single YouTube comment. A `comment` resource can represent a comment about either a video or a channel. In addition, the comment could be a top-level comment or a reply to a top-level comment. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/comments#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/comments#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/comments/list) ` | `GET /comments` | Returns a list of comments that match the API request parameters. | | `[setModerationStatus](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus) ` | `POST /comments/setModerationStatus` | Sets the moderation status of one or more comments. The API request must be authorized by the owner of the channel or video associated with the comments. | | `[insert](https://developers.google.com/youtube/v3/docs/comments/insert) ` | `POST /comments` | Creates a reply to an existing comment. **Note:** To create a top-level comment, use the `[commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) ` method. | | `[delete](https://developers.google.com/youtube/v3/docs/comments/delete) ` | `DELETE /comments` | Deletes a comment. | | `[update](https://developers.google.com/youtube/v3/docs/comments/update) ` | `PUT /comments` | Modifies a comment. | ### I18nLanguages An `**i18nLanguage**` resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location. A user could also manually select the UI language from the YouTube site footer. Each `i18nLanguage` resource identifies a language code and a name. The language code can be used as the value of the `hl` parameter when calling API methods like `videoCategories.list`. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/i18nLanguages#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/i18nLanguages#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) ` | `GET /i18nLanguages` | Returns a list of application languages that the YouTube website supports. | ### I18nRegions An `**i18nRegion**` resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location. A user could also manually select the content region from the YouTube site footer. Each `i18nRegion` resource identifies a region code and a name. The region code can be used as the value of the `regionCode` parameter when calling API methods like `search.list`, `videos.list`, `activities.list`, and `videoCategories.list`. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/i18nRegions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/i18nRegions#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/i18nRegions/list) ` | `GET /i18nRegions` | Returns a list of content regions that the YouTube website supports. | ### Members A `**member**` resource represents a channel member for a YouTube channel. A member provides recurring monetary support to a creator and receives special benefits. For example, members are able to chat when the creator turns on members-only mode for a chat. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/members#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/members#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/members/list) ` | `GET /members` | Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. | ### MembershipsLevels A `**membershipsLevel**` resource identifies a pricing level for the creator that authorized the API request. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/membershipsLevels#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/membershipsLevels#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/membershipsLevels/list) ` | `GET /membershipsLevels` | Returns a collection of zero or more `**membershipsLevel**` resources owned by the channel that authorized the API request. Levels are returned in implicit display order. | ### PlaylistItems A `**playlistItem**` resource identifies another resource, such as a video, that is included in a playlist. In addition, the `playlistItem` resource contains details about the included resource that pertain specifically to how that resource is used in that playlist. YouTube also uses a playlist to identify a channel's list of uploaded videos, with each `playlistItem` in that list representing one uploaded video. You can retrieve the playlist ID for that list from the `[channel resource](https://developers.google.com/youtube/v3/docs/channels) ` for a given channel. You can then use the `[playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) ` method to the list. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/playlistItems#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/playlistItems#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) ` | `DELETE /playlistItems` | Deletes a playlist item. | | `[insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) ` | `POST /playlistItems` | Adds a resource to a playlist. | | `[list](https://developers.google.com/youtube/v3/docs/playlistItems/list) ` | `GET /playlistItems` | Returns a collection of playlist items that match the API request parameters. You can retrieve all of the playlist items in a specified playlist or retrieve one or more playlist items by their unique IDs. | | `[update](https://developers.google.com/youtube/v3/docs/playlistItems/update) ` | `PUT /playlistItems` | Modifies a playlist item. For example, you could update the item's position in the playlist. | ### Playlists A `**playlist**` resource represents a YouTube playlist. A playlist is a collection of videos that can be viewed sequentially and shared with other users. By default, playlists are publicly visible to other users, but playlists can be public or private. YouTube also uses playlists to identify special collections of videos for a channel, such as: * uploaded videos * positively rated (liked) videos * watch history * watch later To be more specific, these lists are associated with a channel, which is a collection of a person, group, or company's videos, playlists, and other YouTube information. You can retrieve the playlist IDs for each of these lists from the `[channel resource](https://developers.google.com/youtube/v3/docs/channels) ` for a given channel. You can then use the `[playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) ` method to retrieve any of those lists. You can also add or remove items from those lists by calling the `[playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) ` and `[playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) ` methods. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/playlists#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/playlists#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[delete](https://developers.google.com/youtube/v3/docs/playlists/delete) ` | `DELETE /playlists` | Deletes a playlist. | | `[list](https://developers.google.com/youtube/v3/docs/playlists/list) ` | `GET /playlists` | Returns a collection of playlists that match the API request parameters. For example, you can retrieve all playlists that the authenticated user owns, or you can retrieve one or more playlists by their unique IDs. | | `[insert](https://developers.google.com/youtube/v3/docs/playlists/insert) ` | `POST /playlists` | Creates a playlist. | | `[update](https://developers.google.com/youtube/v3/docs/playlists/update) ` | `PUT /playlists` | Modifies a playlist. For example, you could change a playlist's title, description, or privacy status. | ### Search A search result contains information about a YouTube video, channel, or playlist that matches the search parameters specified in an API request. While a search result points to a uniquely identifiable resource, like a video, it does not have its own persistent data. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/search#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/search#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/search/list) ` | `GET /search` | Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching `[video](https://developers.google.com/youtube/v3/docs/videos) `, `[channel](https://developers.google.com/youtube/v3/docs/channels) `, and `[playlist](https://developers.google.com/youtube/v3/docs/playlists) ` resources, but you can also configure queries to only retrieve a specific type of resource. | ### Subscriptions A `**subscription**` resource contains information about a YouTube user subscription. A subscription notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/subscriptions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/subscriptions#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[delete](https://developers.google.com/youtube/v3/docs/subscriptions/delete) ` | `DELETE /subscriptions` | Deletes a subscription. | | `[insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert) ` | `POST /subscriptions` | Adds a subscription for the authenticated user's channel. | | `[list](https://developers.google.com/youtube/v3/docs/subscriptions/list) ` | `GET /subscriptions` | Returns subscription resources that match the API request criteria. | ### Thumbnails A `**thumbnail**` resource identifies different thumbnail image sizes associated with a resource. The following characteristics of thumbnail images: * A resource's `snippet.thumbnails` property is an object that identifies the thumbnail images available for that resource. * A `thumbnail` resource contains a series of objects. The name of each object (`default`, `medium`, `high`, etc.) refers to the thumbnail image size. * Different types of resources may support different thumbnail image sizes. * Different types of resources may define different sizes for thumbnail images with the same name. For example, the `default` thumbnail image for a `video` resource is typically 120px by 90px, and the `default` thumbnail image for a `channel` resource is typically 88px by 88px. * Resources of the same type may still have different thumbnail image sizes for certain images depending on the resolution of the original image or content uploaded to YouTube. For example, an HD video may support higher resolution thumbnails than non-HD videos. * Each object that contains information about a thumbnail image size has a `width` property and a `height` property. However, the width and height properties may not be returned for that image. * If an uploaded thumbnail image does not match the required dimensions, the image is resized to match the correct size without changing its aspect ratio. The image is not cropped, but may include black bars so that the size is correct. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/thumbnails#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/thumbnails#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[set](https://developers.google.com/youtube/v3/docs/thumbnails/set) ` | `POST /thumbnails/set` | Uploads a custom video thumbnail to YouTube and sets it for a video. | ### VideoAbuseReportReasons A `**videoAbuseReportReason**` resource contains information about a reason that a video would be flagged for containing abusive content. When your application calls the `[videos.reportAbuse](https://developers.google.com/youtube/v3/docs/videos/reportAbuse) ` method to report an abusive video, the request uses the information from a `videoAbuseReportReason` resource to identify the reason that the video is being reported. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons/list) ` | `GET /videoAbuseReportReasons` | Retrieve a list of reasons that can be used to report abusive videos. | ### VideoCategories A `**videoCategory**` resource identifies a category that has been or could be associated with uploaded videos. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/videoCategories#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videoCategories#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[list](https://developers.google.com/youtube/v3/docs/videoCategories/list) ` | `GET /videoCategories` | Returns a list of categories that can be associated with YouTube videos. | ### Videos A `**video**` resource represents a YouTube video. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/videos#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videos#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[insert](https://developers.google.com/youtube/v3/docs/videos/insert) ` | `POST /videos` | Uploads a video to YouTube and optionally sets the video's metadata. | | `[list](https://developers.google.com/youtube/v3/docs/videos/list) ` | `GET /videos` | Returns a list of videos that match the API request parameters. | | `[delete](https://developers.google.com/youtube/v3/docs/videos/delete) ` | `DELETE /videos` | Deletes a YouTube video. | | `[update](https://developers.google.com/youtube/v3/docs/videos/update) ` | `PUT /videos` | Updates a video's metadata. | | `[rate](https://developers.google.com/youtube/v3/docs/videos/rate) ` | `POST /videos/rate` | Add a like or dislike rating to a video or remove a rating from a video. | | `[getRating](https://developers.google.com/youtube/v3/docs/videos/getRating) ` | `GET /videos/getRating` | Retrieves the ratings that the authorized user gave to a list of specified videos. | | `[reportAbuse](https://developers.google.com/youtube/v3/docs/videos/reportAbuse) ` | `POST /videos/reportAbuse` | Report a video for containing abusive content. | ### Watermarks A `**watermark**` resource identifies an image that displays during playbacks of a specified channel's videos. You can also specify a target channel to which the image will link as well as timing details that determine when the watermark appears during video playbacks and the length of time it is visible. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/watermarks#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/watermarks#properties) . | Method | HTTP request | Description | | --- | --- | --- | | URIs relative to `https://www.googleapis.com/youtube/v3` | | | | `[set](https://developers.google.com/youtube/v3/docs/watermarks/set) ` | `POST /watermarks/set` | Uploads a watermark image to YouTube and sets it for a channel. | | `[unset](https://developers.google.com/youtube/v3/docs/watermarks/unset) ` | `POST /watermarks/unset` | Deletes a channel's watermark image. | Was this helpful? Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-10-06 UTC. Info Chat API --- # Captions: insert  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/captions/insert#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Captions: insert Stay organized with collections Save and categorize content based on your preferences. ======================================================================================================= Uploads a caption track. This method supports media upload. Uploaded files must conform to these constraints: * **Maximum file size:** 100MB * **Accepted Media MIME types:** `text/xml`, `application/octet-stream`, `*/*` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/determine_quota_cost) of 400 units. Common use cases ---------------- Request ------- ### HTTP request POST https://www.googleapis.com/upload/youtube/v3/captions ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication) . | Scope | | --- | | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies the `caption` resource parts that the API response will include. Set the parameter value to `snippet`.

The following list contains the `part` names that you can include in the parameter value:

* `id`
* `snippet` | | **Optional parameters** | | | | `onBehalfOfContentOwner` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
.

**Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `sync` | `boolean`
This parameter has been deprecated. The `**sync**` parameter indicates whether YouTube should automatically synchronize the caption file with the audio track of the video. If you set the value to `true`, YouTube will disregard any time codes that are in the uploaded caption file and generate new time codes for the captions.

You should set the `sync` parameter to `true` if you are uploading a transcript, which has no time codes, or if you suspect the time codes in your file are incorrect and want YouTube to try to fix them. | ### Request body Provide a `[caption](https://developers.google.com/youtube/v3/docs/captions#resource) ` resource in the request body. For that resource: You must specify a value for these properties: * `snippet.videoId` * `snippet.language` * `snippet.name` You can set values for these properties: * `snippet.videoId` * `snippet.language` * `snippet.name` * `snippet.isDraft` Response -------- If successful, this method returns a `[caption](https://developers.google.com/youtube/v3/docs/captions#resource) ` resource in the response body. Errors ------ The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors) . | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `contentRequired` | The request does not contain the caption track contents. | | `conflict (409)` | `captionExists` | The specified video already has a caption track with the given `snippet.language` and `snippet.name`. A video can have multiple tracks for the same language, but each track must have a different name.

There are multiple ways to address the error. You could delete the existing track and then insert a new one or change the name of the new track before inserting it. | | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to upload the caption track. The request might not be properly authorized. | | `invalidValue (400)` | `invalidMetadata` | The request contains invalid metadata values, which prevent the track from being created. Confirm that the request specifies valid values for the `snippet.language`, `snippet.name`, and `snippet.videoId` properties. The `snippet.isDraft` property can also be included, but it is not required. | | `notFound (404)` | `videoNotFound` | The video identified by the `videoId` parameter couldn't be found. | | `invalidValue (400)` | `nameTooLong` | The `snippet.name` specified in the request is too long. The maximum length supported is 150 characters. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Channels: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/channels/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Channels: list Stay organized with collections Save and categorize content based on your preferences. ===================================================================================================== **Note:** The `channel` resource's `[statistics.subscriberCount](https://developers.google.com/youtube/v3/docs/channels#statistics.subscriberCount) ` property value has been updated to reflect a YouTube policy change that affects the way that subscriber counts are displayed. For more information, see [Revision History](https://developers.google.com/youtube/v3/revision_history#release_notes_09_10_2019) or the [YouTube Help Center](https://support.google.com/youtube/answer/6051134) . Returns a collection of zero or more `**channel**` resources that match the request criteria. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Common use cases ---------------- Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/channels ### Authorization A request that retrieves the `auditDetails` part for a `channel` resource must provide an authorization token that contains the `https://www.googleapis.com/auth/youtubepartner-channel-audit` scope. In addition, any token that uses that scope must be revoked when the MCN decides to accept or reject the channel or within two weeks of the date that the token was issued. ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies a comma-separated list of one or more `channel` resource properties that the API response will include.

If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in a `channel` resource, the `contentDetails` property contains other properties, such as the `uploads` properties. As such, if you set `**part=contentDetails**`, the API response will also contain all of those nested properties.

The following list contains the `part` names that you can include in the parameter value:

* `auditDetails`
* `brandingSettings`
* `contentDetails`
* `contentOwnerDetails`
* `id`
* `localizations`
* `snippet`
* `statistics`
* `status`
* `topicDetails` | | **Filters (specify exactly one of the following parameters)** | | | | `categoryId` | `string`
This parameter has been deprecated. The `**categoryId**` parameter specified a [YouTube guide category](https://developers.google.com/youtube/v3/docs/guideCategories)
and could be used to request YouTube channels associated with that category. | | `forHandle` | `string`
The `**forHandle**` parameter specifies a YouTube handle, thereby requesting the channel associated with that handle. The parameter value can be prepended with an `@` symbol. For example, to retrieve the resource for the "Google for Developers" channel, set the `forHandle` parameter value to either `GoogleDevelopers` or `@GoogleDevelopers`. | | `forUsername` | `string`
The `**forUsername**` parameter specifies a YouTube username, thereby requesting the channel associated with that username. | | `id` | `string`
The `**id**` parameter specifies a comma-separated list of the YouTube channel ID(s) for the resource(s) that are being retrieved. In a `channel` resource, the `id` property specifies the channel's YouTube channel ID. | | `managedByMe` | `boolean`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
.

**Note:** This parameter is intended exclusively for YouTube content partners.

Set this parameter's value to `true` to instruct the API to only return channels managed by the content owner that the `**onBehalfOfContentOwner**` parameter specifies. The user must be authenticated as a CMS account linked to the specified content owner and `**onBehalfOfContentOwner**` must be provided. | | `mine` | `boolean`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. Set this parameter's value to `true` to instruct the API to only return channels owned by the authenticated user. | | **Optional parameters** | | | | `hl` | `string`
The `**hl**` parameter instructs the API to retrieve localized resource metadata for a specific [application language that the YouTube website supports](https://developers.google.com/youtube/v3/docs/i18nLanguages)
. The parameter value must be a language code included in the list returned by the `[i18nLanguages.list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) ` method.

If localized resource details are available in that language, the resource's `snippet.localized` object will contain the localized values. However, if localized details are not available, the `snippet.localized` object will contain resource details in the resource's [default language](https://developers.google.com/youtube/v3/docs/channels#snippet.defaultLanguage)
. | | `maxResults` | `unsigned integer`
The `**maxResults**` parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
.

**Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `pageToken` | `string`
The `**pageToken**` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#channelListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": \[\ [channel Resource](https://developers.google.com/youtube/v3/docs/channels#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#channelListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. Note that this property is not included in the API response if the corresponding API request set the `[managedByMe](https://developers.google.com/youtube/v3/docs/channels/list#managedByMe) ` parameter to `true`. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of channels that match the request criteria. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors) . | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `invalidCriteria` | A maximum of one of the following filters may be specified:`id`, `categoryId`, `mine`, `managedByMe`, `forHandle`, `forUsername`. In case of content owner authentication via the `onBehalfOfContentOwner` parameter, only the `id` or `managedByMe` may be specified. | | `forbidden (403)` | `channelForbidden` | The channel specified by the `id` parameter does not support the request or the request is not properly authorized. | | `notFound (404)` | `categoryNotFound` | The category identified by the `categoryId` parameter cannot be found. Use the [guideCategories.list](https://developers.google.com/youtube/v3/docs/guideCategories/list)
method to retrieve a list of valid values. | | `notFound (404)` | `channelNotFound` | The channel specified in the `id` parameter cannot be found. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # I18nLanguages: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) I18nLanguages: list Stay organized with collections Save and categorize content based on your preferences. ========================================================================================================== Returns a list of application languages that the YouTube website supports. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Common use cases ---------------- Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/i18nLanguages ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies the `i18nLanguage` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Optional parameters** | | | | `hl` | `string`
The `**hl**` parameter specifies the language that should be used for text values in the API response. The default value is `en_US`. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#i18nLanguageListResponse", "etag": etag, "items": \[\ [i18nLanguage resource](https://developers.google.com/youtube/v3/docs/i18nLanguages#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#i18nLanguageListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `items[]` | `list`
A list of supported i18n languages. In this map, the i18n language ID is the map key, and its value is the corresponding `i18nLanguage` resource. | Errors ------ The API does not define any error messages that are unique to this API method. However, this method could still return general API errors listed in the [error message](https://developers.google.com/youtube/v3/docs/errors#general) documentation. Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # CommentThreads: insert  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/commentThreads/insert#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) CommentThreads: insert Stay organized with collections Save and categorize content based on your preferences. ============================================================================================================= Creates a new top-level comment. To add a reply to an existing comment, use the `[comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert) ` method instead. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. Common use cases ---------------- Request ------- ### HTTP request POST https://www.googleapis.com/youtube/v3/commentThreads ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication) ). | Scope | | --- | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter identifies the properties that the API response will include. Set the parameter value to `snippet`. The `snippet` part has a quota cost of 2 units.

The following list contains the `part` names that you can include in the parameter value:

* `id`
* `replies`
* `snippet` | ### Request body Provide a [commentThread resource](https://developers.google.com/youtube/v3/docs/commentThreads#resource) in the request body. For that resource, you must specify a value for the following properties: * `snippet.channelId` * `snippet.videoId` * `snippet.topLevelComment.snippet.textOriginal` Response -------- If successful, this method returns a [commentThread resource](https://developers.google.com/youtube/v3/docs/commentThreads#resource) in the response body. Errors ------ The following table identifies error messages that the API could return in response to a call to this method. For more details, see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `channelOrVideoIdMissing` | Each comment thread must be linked to a video. Make sure the resource specifies values for the `[snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) ` and the `[snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) ` properties. A comment on a video appears on the video's watch page. | | `badRequest (400)` | `commentTextRequired` | The `comment` resource that is being inserted must specify a value for the `snippet.topLevelComment.snippet.textOriginal` property. Comments cannot be empty. | | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being inserted contains too many characters in the `snippet.topLevelComment.snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentThreadMetadata` | The request metadata is invalid. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment thread couldn't be created due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google Account to insert a comment or comment thread. | | `notFound (404)` | `channelNotFound` | The specified channel couldn't be found. Check the value of the `[snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) ` property to ensure it is correct. | | `notFound (404)` | `videoNotFound` | The specified video couldn't be found. Check the value of the `[snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) ` property to ensure it is correct. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Comments: delete  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/comments/delete#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Comments: delete Stay organized with collections Save and categorize content based on your preferences. ======================================================================================================= Deletes a comment. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. Common use cases ---------------- Request ------- ### HTTP request DELETE https://www.googleapis.com/youtube/v3/comments ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication) ). | Scope | | --- | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `id` | `string`
The `**id**` parameter specifies the comment ID for the resource that is being deleted. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns an HTTP `204` response code (`No Content`). Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | The comment could not be deleted because of insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | The specified comment could not be found. Check the value of the request's `[id](https://developers.google.com/youtube/v3/docs/comments/delete#id) ` parameter to ensure that it is correct. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Members  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/members#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Members Stay organized with collections Save and categorize content based on your preferences. ============================================================================================== Note: As of March 31, 2020, the `members` endpoint replaces the `sponsors` endpoint, which is now deprecated and will no longer be supported on or after September 30, 2020. API clients should update calls to the `sponsors.list` method to use the `members.list` method instead. This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. A `**member**` resource represents a channel member for a YouTube channel. A member provides recurring monetary support to a creator and receives special benefits. For example, members are able to chat when the creator turns on members-only mode for a chat. Methods ------- The API supports the following methods for `member` resources: [list](https://developers.google.com/youtube/v3/docs/members/list) Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. Resource representation ----------------------- The following JSON structure shows the format of a `member` resource: { "[kind](https://developers.google.com/youtube/v3/docs/members#kind) ": "youtube#member", "[etag](https://developers.google.com/youtube/v3/docs/members#etag) ": etag, "[snippet](https://developers.google.com/youtube/v3/docs/members#snippet) ": { "[creatorChannelId](https://developers.google.com/youtube/v3/docs/members#creatorChannelId) ": string, "[memberDetails](https://developers.google.com/youtube/v3/docs/members#snippet.memberDetails) ": { "[channelId](https://developers.google.com/youtube/v3/docs/members#snippet.memberDetails.channelId) ": string, "[channelUrl](https://developers.google.com/youtube/v3/docs/members#snippet.memberDetails.channelUrl) ": string, "[displayName](https://developers.google.com/youtube/v3/docs/members#snippet.memberDetails.displayName) ": string, "[profileImageUrl](https://developers.google.com/youtube/v3/docs/members#snippet.memberDetails.profileImageUrl) ": string }, "[membershipsDetails](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails) ": { "[highestAccessibleLevel](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.highestAccessibleLevel) ": string, "[highestAccessibleLevelDisplayName](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.highestAccessibleLevelDisplayName) ": string, "[accessibleLevels](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.accessibleLevels[]) ": \[\ string\ \], "[membershipsDuration](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDuration) ": { "[memberSince](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDuration.memberSince) ": datetime, "[memberTotalDurationMonths](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDuration.memberTotalDurationMonths) ": integer, }, "[membershipsDurationAtLevel](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[]) ": \[\ {\ "[level](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[].level)\ ": string,\ "[memberSince](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[].memberSince)\ ": datetime,\ "[memberTotalDurationMonths](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[].memberTotalDurationMonths)\ ": integer,\ }\ \] } } } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#member`. | | `etag` | `etag`
The Etag of this resource. | | `snippet` | `object`
The `snippet` object contains details about the member. | | `snippet.creatorChannelId` | `string`
The YouTube channel ID of the creator that offers memberships. | | `snippet.memberDetails` | `object`
This object contains profile data about the YouTube channel that is paying for the membership.

Note that a channel can have members with unavailable profile data. For example, this occurs with members who have deleted their channels but are still paying for memberships. Note that these members can still access their membership benefits.

API responses include resources for those members to ensure accurate counts even though the profile details inside the `memberDetails` object are not set. The `[membershipsDetails](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails) ` are still provided for such members. | | `snippet.memberDetails.channelId` | `string`
The YouTube channel ID of the member channel. If it is set, the channel ID can also be treated as a unique identifier for the member. If it is not set, the member cannot be uniquely identified, but the resource still conveys membership details such as the levels that the member can access and the duration of their membership. | | `snippet.memberDetails.channelUrl` | `string`
The channel's URL. | | `snippet.memberDetails.displayName` | `string`
The channel's display name. | | `snippet.memberDetails.profileImageUrl` | `string`
The channel's avatar URL. | | `snippet.membershipsDetails` | `object`
This object contains membership details for the member channel. | | `snippet.membershipsDetails.highestAccessibleLevel` | `string`
The ID of the highest membership level that the member channel can currently access. The value corresponds to the `[id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id) ` property value in a `membershipsLevel` resource. | | `snippet.membershipsDetails.highestAccessibleLevelDisplayName` | `string`
The name of the highest membership level that the member channel can currently access. The value corresponds to the `[displayName](https://developers.google.com/youtube/v3/docs/membershipsLevels#snippet.levelDetails.displayName) ` property value in a `membershipsLevel` resource. | | `snippet.membershipsDetails.accessibleLevels[]` | `list (of strings)`
A list of IDs for all membership levels that the user can currently access. The list includes the currently active level and all levels below it. | | `snippet.membershipsDuration` | `object`
This object contains information about the overall duration of the current member's membership without regard to pricing levels. The `[snippet.membershipsDetails.membershipsDurationAtLevel[]](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[]) ` property then contains a list of objects that contain details about a period of the membership during which the member had access to a particular membership level.

The following example shows how these properties work: A member purchases a new membership in January at membership level 1 and has that membership until March. In April and May, the member does not have a membership. In June, the member restarts their membership, again at level 1. Then, in August, the member upgrades their membership to level 2. So, if an API call is made in October, the `member` resource would contain the following:

"membershipsDetails": {
"membershipsDuration": {
"memberSince": "2020-06-01T12:00:00",
"memberTotalDurationMonths": 7,
},
"membershipsDurationAtLevel": \[
{
"level": "level\_1\_ID",
"memberSince": "2020-06-01T12:00:00",
"memberTotalDurationMonths": 7
},
{
"level": "level\_2\_ID",
"memberSince": "2020-08-01T12:00:00",
"memberTotalDurationMonths": 2
},
\]
} | | `snippet.membershipsDuration.memberSince` | `datetime`
The date and time that the member's current membership started. In other words, the member has continuously had a membership since this date and time. Note that different periods of the membership might have been spent at different membership levels. | | `snippet.membershipsDuration.memberTotalDurationMonths` | `integer`
The number of months, rounded down to the nearest integer, that the user has been a member. The value reflects the number of complete months that the member has had a membership, but the number does not imply that the member has continuously had a membership for that many months. | | `snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[]` | `list (of objects)`
A list of objects, in which each object contains details about a period of the membership during which the member had access to a particular membership level. The list includes one object for each membership level that the member can currently access. | | `snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level` | `string`
The membership level ID. The value corresponds to the `[id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id) ` property value in a `membershipsLevel` resource. | | `snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince` | `datetime`
The date and time from which the member has had access to the specified membership level. In other words, the member has continuously had access to the level since this date and time. Note that different periods of the membership might have been spent at higher membership levels. | | `snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths` | `integer`
The number of months, rounded down to the nearest integer, that the user has had access to the specified level. The value reflects the number of complete months that the member has had access to the level, but the number does not imply that the member has continuously had a membership for that many months. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # I18nRegions  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/i18nRegions#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) I18nRegions Stay organized with collections Save and categorize content based on your preferences. ================================================================================================== An `**i18nRegion**` resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location. A user could also manually select the desired content region from the YouTube site footer. Each `i18nRegion` resource identifies a region code and a name. The region code can be used as the value of the `regionCode` parameter when calling API methods like `search.list`, `videos.list`, `activities.list`, and `videoCategories.list`. Methods ------- The API supports the following methods for `i18nRegions` resources: [list](https://developers.google.com/youtube/v3/docs/i18nRegions/list) Returns a list of content regions that the YouTube website supports. [Try it now](https://developers.google.com/youtube/v3/docs/i18nRegions/list#usage) . Resource representation ----------------------- The following JSON structure shows the format of a `i18nRegions` resource: { "[kind](https://developers.google.com/youtube/v3/docs/i18nRegions#kind) ": "youtube#i18nRegion", "[etag](https://developers.google.com/youtube/v3/docs/i18nRegions#etag) ": etag, "[id](https://developers.google.com/youtube/v3/docs/i18nRegions#id) ": string, "[snippet](https://developers.google.com/youtube/v3/docs/i18nRegions#snippet) ": { "[gl](https://developers.google.com/youtube/v3/docs/i18nRegions#snippet.gl) ": string, "[name](https://developers.google.com/youtube/v3/docs/i18nRegions#snippet.name) ": string } } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#i18nRegion`. | | `etag` | `etag`
The Etag of this resource. | | `id` | `string`
The ID that YouTube uses to uniquely identify the i18n region. | | `snippet` | `object`
The `snippet` object contains basic details about the i18n region, such as its region code and name. | | `snippet.gl` | `string`
The two-letter ISO country code that identifies the region. | | `snippet.name` | `string`
The name of the region. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # PlaylistImages: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/playlistImages/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) PlaylistImages: list Stay organized with collections Save and categorize content based on your preferences. =========================================================================================================== Returns a collection of playlist images that match the API request parameters. You can retrieve the playlist image of a specified playlist or retrieve one or more playlist images by their unique IDs. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/playlistImages ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication) ). | Scope | | --- | | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`

The `**part**` parameter specifies a comma-separated list of one or more `playlistImage` resource properties that the API response will include.

If the parameter identifies a property that contains child properties, the child properties will be included in the response. | | **Filters (specify exactly one of the following parameters)** | | | | `id` | `string`
The `**id**` parameter specifies a comma-separated list of one or more unique playlist image IDs. | | `playlistId` | `string`
The `**playlistId**` parameter specifies the unique ID of the playlist for which you want to retrieve playlist images. Note that even though this is an optional parameter, every request to retrieve playlist images must specify a value for either the `id` parameter or the `playlistId` parameter. | | **Optional parameters** | | | | `maxResults` | `unsigned integer`
The `**maxResults**` parameter specifies the maximum number of images that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. **Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `onBehalfOfContentOwnerChannel` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. **Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwnerChannel**` parameter specifies the YouTube channel ID of the channel to which a video is being added. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. In addition, the request must be authorized using a CMS account that is linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. Finally, the channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies.

This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. | | `pageToken` | `string`
The `**pageToken**` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#playlistImageListResponse", "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": \[\ [playlistImages Resource](https://developers.google.com/youtube/v3/docs/playlistImages#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#playlistImageListResponse`. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of playlist images that match the request criteria. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Members: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/members/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Members: list Stay organized with collections Save and categorize content based on your preferences. ==================================================================================================== Note: This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 2 units. Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/members ### Authorization This request requires authorization with the following scope: | Scope | | --- | | `https://www.googleapis.com/auth/youtube.channel-memberships.creator` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies the `member` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Optional parameters** | | | | `mode` | `string`
The `**mode**` parameter indicates which members will be included in the API response. Set the parameter value to one of the following values:

* `all_current` (default) - List current members, from newest to oldest. When this value is used, the end of the list is reached when the API response does not contain a `[nextPageToken](https://developers.google.com/youtube/v3/docs/members/list#nextPageToken) `.
* `updates` - List only members that joined or upgraded since the previous API call. Note that the first call starts a new stream of updates but does not actually return any members. To start retrieving the membership updates, you need to poll the endpoint using the `nextPageToken` at your desired frequency.

Note that when this value is used, the API response always contains a `[nextPageToken](https://developers.google.com/youtube/v3/docs/members/list#nextPageToken) `. | | `maxResults` | `unsigned integer`
The `**maxResults**` parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `1000`, inclusive. The default value is `5`. | | `pageToken` | `string`
The `**pageToken**` parameter identifies a specific page in the result set that should be returned. The token is specific to the `[mode](https://developers.google.com/youtube/v3/docs/members/list#mode) ` used with the original API request, so you cannot use a page token retrieved with one mode to subsequently switch to a different mode. | | `hasAccessToLevel` | `string`
The `**hasAccessToLevel**` parameter value is a level ID that specifies the minimum level that members in the result set should have. | | `filterByMemberChannelId` | `string`
The `**filterByMemberChannelId**` parameter specifies a comma-separated list of channel IDs that can be used to check the membership status of specific users. For example, `UC_1,UC_2,UC_3`. A maximum of 100 channels can be specified per call. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "[kind](https://developers.google.com/youtube/v3/docs/members/list#kind) ": "youtube#memberListResponse", "[etag](https://developers.google.com/youtube/v3/docs/members/list#etag) ": etag, "[nextPageToken](https://developers.google.com/youtube/v3/docs/members/list#nextPageToken) ": string, "[pageInfo](https://developers.google.com/youtube/v3/docs/members/list#pageInfo) ": { "[totalResults](https://developers.google.com/youtube/v3/docs/members/list#totalResults) ": integer, "[resultsPerPage](https://developers.google.com/youtube/v3/docs/members/list#resultsPerPage) ": integer }, "[items](https://developers.google.com/youtube/v3/docs/members/list#items) ": \[\ [member Resource](https://developers.google.com/youtube/v3/docs/members#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#memberListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. Page tokens can expire, and your application should drop the token and call the API without a `pageToken` to start a new request. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of members that match the request criteria. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | | `badRequest (400)` | `invalidMode` | The `[mode](https://developers.google.com/youtube/v3/docs/members/list#mode) ` parameter value is invalid. This error might occur if the `[pageToken](https://developers.google.com/youtube/v3/docs/members/list#pageToken) ` parameter specifies a token that was retrieved using a different mode than the one specified. | | `badRequest (400)` | `invalidPageToken` | The `[pageToken](https://developers.google.com/youtube/v3/docs/members/list#pageToken) ` parameter value is invalid. This error can occur if the page token used in the request has expired or is not recognized. | | `badRequest (400)` | `invalidHasAccessToLevel` | The `[hasAccessToLevel](https://developers.google.com/youtube/v3/docs/members/list#hasAccessToLevel) ` parameter value is invalid. There is no level with the specified `[id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id) `. | | `badRequest (400)` | `invalidFilterByMemberChannelId` | The `[filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/members/list#filterByMemberChannelId) ` parameter value is invalid. This error occurs if the `[filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/members/list#filterByMemberChannelId) ` parameter value specifies more than 100 channels. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # CommentThreads: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/commentThreads/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) CommentThreads: list Stay organized with collections Save and categorize content based on your preferences. =========================================================================================================== Returns a list of comment threads that match the API request parameters. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Common use cases ---------------- Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/commentThreads ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies a comma-separated list of one or more `commentThread` resource properties that the API response will include.

The following list contains the `part` names that you can include in the parameter value:

* `id`
* `replies`
* `snippet` | | **Filters (specify exactly one of the following parameters)** | | | | `allThreadsRelatedToChannelId` | `string`
The `**allThreadsRelatedToChannelId**` parameter instructs the API to return all comment threads associated with the specified channel. | | `id` | `string`
The `**id**` parameter specifies a comma-separated list of comment thread IDs for the resources that should be retrieved. | | `videoId` | `string`
The `**videoId**` parameter instructs the API to return comment threads associated with the specified video ID. | | **Optional parameters** | | | | `maxResults` | `unsigned integer`
The `**maxResults**` parameter specifies the maximum number of items that should be returned in the result set.

**Note:** This parameter is not supported for use in conjunction with the `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter. Acceptable values are `1` to `100`, inclusive. The default value is `20`. | | `moderationStatus` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. Set this parameter to limit the returned comment threads to a particular moderation state.

**Note:** This parameter is not supported for use in conjunction with the `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter. The default value is `published`.

Acceptable values are:

* `**heldForReview**` – Retrieve comment threads that are awaiting review by a moderator. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment are awaiting review.
* `**likelySpam**` – Retrieve comment threads classified as likely to be spam. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment is considered likely to be spam.
* `**published**` – Retrieve threads of published comments. This is the default value. A comment thread can be included in the response if its top-level comment has been published. | | `order` | `string`
The `**order**` parameter specifies the order in which the API response should list comment threads. Valid values are:

* `time` - Comment threads are ordered by time. This is the default behavior.
* `relevance` - Comment threads are ordered by relevance.

**Note:** This parameter is not supported for use in conjunction with the `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter. | | `pageToken` | `string`
The `**pageToken**` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` property identifies the next page of the result that can be retrieved.

**Note:** This parameter is not supported for use in conjunction with the `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter. | | `searchTerms` | `string`
The `**searchTerms**` parameter instructs the API to limit the API response to only contain comments that contain the specified search terms.

**Note:** This parameter is not supported for use in conjunction with the `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter. | | `textFormat` | `string`
Set this parameter's value to `html` or `plainText` to instruct the API to return the comments left by users in html formatted or in plain text. The default value is `html`.

Acceptable values are:

* `**html**` – Returns the comments in HTML format. This is the default value.
* `**plainText**` – Returns the comments in plain text format. | ### Request body Don't provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#commentThreadListResponse", "etag": etag, "nextPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": \[\ [commentThread Resource](https://developers.google.com/youtube/v3/docs/commentThreads#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#commentThreadListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of comment threads that match the request criteria. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. For more details, see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `operationNotSupported` | The `id` filter is only compatible with comments based on Google+. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `commentsDisabled` | The video identified by the `[videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) ` parameter has disabled comments. | | `forbidden (403)` | `forbidden` | One or more of the requested comment threads cannot be retrieved due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `channelNotFound` | The channel identified by the `[allThreadsRelatedToChannelId](https://developers.google.com/youtube/v3/docs/commentThreads/list#allThreadsRelatedToChannelId) ` parameter couldn't be found. | | `notFound (404)` | `commentThreadNotFound` | One or more of the specified comment threads cannot be found. Check the values of the request's `[id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) ` parameter to ensure that it is correct. | | `notFound (404)` | `videoNotFound` | The video identified by the `[videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) ` parameter couldn't be found. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Subscriptions: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/subscriptions/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Subscriptions: list Stay organized with collections Save and categorize content based on your preferences. ========================================================================================================== Returns subscription resources that match the API request criteria. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Common use cases ---------------- Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/subscriptions ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies a comma-separated list of one or more `subscription` resource properties that the API response will include.

If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in a `subscription` resource, the `snippet` property contains other properties, such as a display title for the subscription. If you set `**part=snippet**`, the API response will also contain all of those nested properties.

The following list contains the `part` names that you can include in the parameter value:

* `contentDetails`
* `id`
* `snippet`
* `subscriberSnippet` | | **Filters (specify exactly one of the following parameters)** | | | | `channelId` | `string`
The `**channelId**` parameter specifies a YouTube channel ID. The API will only return that channel's subscriptions. | | `id` | `string`
The `**id**` parameter specifies a comma-separated list of the YouTube subscription ID(s) for the resource(s) that are being retrieved. In a `subscription` resource, the `id` property specifies the YouTube subscription ID. | | `mine` | `boolean`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. Set this parameter's value to `true` to retrieve a feed of the authenticated user's subscriptions. | | `myRecentSubscribers` | `boolean`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. Set this parameter's value to `true` to retrieve a feed of the subscribers of the authenticated user in reverse chronological order (newest first).

Note that the maximum number of subscribers returned through this API might be limited. | | `mySubscribers` | `boolean`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. Set this parameter's value to `true` to retrieve a feed of the subscribers of the authenticated user in no particular order. Note that the maximum number of subscribers returned through this API might be limited. | | **Optional parameters** | | | | `forChannelId` | `string`
The `**forChannelId**` parameter specifies a comma-separated list of channel IDs. The API response will then only contain subscriptions matching those channels. | | `maxResults` | `unsigned integer`
The `**maxResults**` parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string`
**Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `onBehalfOfContentOwnerChannel` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. **Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwnerChannel**` parameter specifies the YouTube channel ID of the channel to which a video is being added. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. In addition, the request must be authorized using a CMS account that is linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. Finally, the channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies.

This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. | | `order` | `string`
The `**order**` parameter specifies the method that will be used to sort resources in the API response. The default value is `SUBSCRIPTION_ORDER_RELEVANCE`.

Acceptable values are:

* `**alphabetical**` – Sort alphabetically.
* `**relevance**` – Sort by relevance.
* `**unread**` – Sort by order of activity. | | `pageToken` | `string`
The `**pageToken**` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#subscriptionListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": \[\ [subscription Resource](https://developers.google.com/youtube/v3/docs/subscriptions#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#subscriptionListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of subscriptions that match the request criteria. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `forbidden (403)` | `accountClosed` | Subscriptions could not be retrieved because the subscriber's account is closed. | | `forbidden (403)` | `accountSuspended` | Subscriptions could not be retrieved because the subscriber's account is suspended. | | `forbidden (403)` | `subscriptionForbidden` | The requester is not allowed to access the requested subscriptions. | | `notFound (404)` | `subscriberNotFound` | The subscriber identified with the request cannot be found. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # MembershipsLevels: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/membershipsLevels/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) MembershipsLevels: list Stay organized with collections Save and categorize content based on your preferences. ============================================================================================================== Note: This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. Lists membership levels for the channel that authorized the request. Levels are returned in implicit display order. API requests to this method yield one of the following responses: * If the creator has enabled channel memberships and has pricing levels, then the API response contains the list of levels. * If the creator has enabled channel memberships but has not defined pricing levels, then the API response contains an empty list. * If the creator has not enabled channel memberships, the API returns a `[channelMembershipsNotEnabled](https://developers.google.com/youtube/v3/docs/membershipsLevels/list#errors) ` error. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/membershipsLevels This request requires authorization with the following scope: | Scope | | --- | | `https://www.googleapis.com/auth/youtube.channel-memberships.creator` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies the `membershipsLevel` resource properties that the API response will include. The parameter value is a comma-separated list of resource parts. The following list shows the parts that can be retrieved:

* `id`
* `snippet` | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#membershipsLevelListResponse", "etag": etag, "items": \[\ [membershipsLevel Resource](https://developers.google.com/youtube/v3/docs/membershipsLevels#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#membershipsLevelListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `items[]` | `list`
A list of `membershipsLevel` resources owned by the channel that authorized the API request. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # PlaylistItems: delete  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/playlistItems/delete#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) PlaylistItems: delete Stay organized with collections Save and categorize content based on your preferences. ============================================================================================================ Deletes a playlist item. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. Common use cases ---------------- Request ------- ### HTTP request DELETE https://www.googleapis.com/youtube/v3/playlistItems ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication) . | Scope | | --- | | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `id` | `string`
The `**id**` parameter specifies the YouTube playlist item ID for the playlist item that is being deleted. In a `playlistItem` resource, the `id` property specifies the playlist item's ID. | | **Optional parameters** | | | | `onBehalfOfContentOwner` | `string`
**Note:** The `**onBehalfOfContentOwner**` parameter is intended exclusively for YouTube content partners and can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
.

This parameter is designed for YouTube content partners that own and manage many different YouTube channels. It enables users affiliated with the content owner to authenticate once and then be able to access and manage all of the content owner's video and channel data, without having to provide authentication credentials for each individual channel.

When the parameter is present, its value identifies a content owner, and the request's authorization credentials identify a YouTube user who is authorized to act on behalf of that content owner. The account that the user authenticates with must be [linked to the specified content owner](https://support.google.com/youtube/answer/4524878)
in the YouTube Creator Studio settings. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns an HTTP `204 No Content` status code. Errors ------ The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors) . | Error type | Error detail | Description | | --- | --- | --- | | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to delete the specified playlist item. | | `notFound (404)` | `playlistItemNotFound` | The playlist item identified with the request's `id` parameter cannot be found. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to delete videos from the specified playlist. For example, you can't delete a video from your uploaded videos playlist. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Thumbnails: set  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/thumbnails/set#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Thumbnails: set Stay organized with collections Save and categorize content based on your preferences. ====================================================================================================== Uploads a custom video thumbnail to YouTube and sets it for a video. This method supports media upload. Uploaded files must conform to these constraints: * **Maximum file size:** 2MB * **Accepted Media MIME types:** `image/jpeg`, `image/png`, `application/octet-stream` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of approximately 50 units. Common use cases ---------------- Request ------- ### HTTP request POST https://www.googleapis.com/upload/youtube/v3/thumbnails/set ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication) ). | Scope | | --- | | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube.upload` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `videoId` | `string`
The `**videoId**` parameter specifies a YouTube video ID for which the custom video thumbnail is being provided. | | **Optional parameters** | | | | `onBehalfOfContentOwner` | `string`
**Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body The body of the request contains the thumbnail image that you are uploading. The request body does not contain a `[thumbnail](https://developers.google.com/youtube/v3/docs/thumbnails#resource-representation) ` resource. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#thumbnailSetResponse", "etag": etag, "items": \[\ [thumbnail resource](https://developers.google.com/youtube/v3/docs/thumbnails#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#thumbnailSetResponse`. | | `etag` | `etag`
The Etag of this resource. | | `items[]` | `list`
A list of thumbnails. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `badRequest (400)` | `invalidImage` | The provided image content is invalid. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the image content. | | `forbidden (403)` | `forbidden` | The thumbnail can't be set for the specified video. The request might not be properly authorized. | | `forbidden (403)` | `forbidden` | The authenticated user doesn't have permissions to upload and set custom video thumbnails. | | `notFound (404)` | `videoNotFound` | The video that you are trying to insert a thumbnail image for cannot be found. Check the value of the request's `videoId` parameter to ensure that it is correct. | | `tooManyRequests (429)` | `uploadRateLimitExceeded` | The channel has uploaded too many thumbnails recently. Please try the request again later. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Search  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/search#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Search Stay organized with collections Save and categorize content based on your preferences. ============================================================================================= A `**search**` result contains information about a YouTube video, channel, or playlist that matches the search parameters specified in an API request. While a search result points to a uniquely identifiable resource, like a video, it does not have its own persistent data. Methods ------- The API supports the following methods for search: [list](https://developers.google.com/youtube/v3/docs/search/list) Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching `[video](https://developers.google.com/youtube/v3/docs/videos) `, `[channel](https://developers.google.com/youtube/v3/docs/channels) `, and `[playlist](https://developers.google.com/youtube/v3/docs/playlists) ` resources, but you can also configure queries to only retrieve a specific type of resource. [Try it now](https://developers.google.com/youtube/v3/docs/search/list#usage) . Resource representation ----------------------- The following JSON structure shows the format of a search result: { "[kind](https://developers.google.com/youtube/v3/docs/search#kind) ": "youtube#searchResult", "[etag](https://developers.google.com/youtube/v3/docs/search#etag) ": etag, "[id](https://developers.google.com/youtube/v3/docs/search#id) ": { "[kind](https://developers.google.com/youtube/v3/docs/search#id.kind) ": string, "[videoId](https://developers.google.com/youtube/v3/docs/search#id.videoId) ": string, "[channelId](https://developers.google.com/youtube/v3/docs/search#id.channelId) ": string, "[playlistId](https://developers.google.com/youtube/v3/docs/search#id.playlistId) ": string }, "[snippet](https://developers.google.com/youtube/v3/docs/search#snippet) ": { "[publishedAt](https://developers.google.com/youtube/v3/docs/search#snippet.publishedAt) ": datetime, "[channelId](https://developers.google.com/youtube/v3/docs/search#snippet.channelId) ": string, "[title](https://developers.google.com/youtube/v3/docs/search#snippet.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/search#snippet.description) ": string, "[thumbnails](https://developers.google.com/youtube/v3/docs/search#snippet.thumbnails) ": { (key): { "[url](https://developers.google.com/youtube/v3/docs/search#snippet.thumbnails.(key).url) ": string, "[width](https://developers.google.com/youtube/v3/docs/search#snippet.thumbnails.(key).width) ": unsigned integer, "[height](https://developers.google.com/youtube/v3/docs/search#snippet.thumbnails.(key).height) ": unsigned integer } }, "[channelTitle](https://developers.google.com/youtube/v3/docs/search#snippet.channelTitle) ": string, "[liveBroadcastContent](https://developers.google.com/youtube/v3/docs/search#snippet.liveBroadcastContent) ": string } } ### Properties The following table defines the properties that appear in a search result: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#searchResult`. | | `etag` | `etag`
The Etag of this resource. | | `id` | `object`
The `id` object contains information that can be used to uniquely identify the resource that matches the search request. | | `id.kind` | `string`
The type of the API resource. | | `id.videoId` | `string`
If the `id.type` property's value is `youtube#video`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a video that matches the search query. | | `id.channelId` | `string`
If the `id.type` property's value is `youtube#channel`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a channel that matches the search query. | | `id.playlistId` | `string`
If the `id.type` property's value is `youtube#playlist`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a playlist that matches the search query. | | `snippet` | `object`
The `snippet` object contains basic details about a search result, such as its title or description. For example, if the search result is a video, then the title will be the video's title and the description will be the video's description. | | `snippet.publishedAt` | `datetime`
The creation date and time of the resource that the search result identifies. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime)
format. | | `snippet.channelId` | `string`
The value that YouTube uses to uniquely identify the channel that published the resource that the search result identifies. | | `snippet.title` | `string`
The title of the search result. | | `snippet.description` | `string`
A description of the search result. | | `snippet.thumbnails` | `object`
A map of thumbnail images associated with the search result. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail. | | `snippet.thumbnails.(key)` | `object`
Valid key values are:

* `default` – The default thumbnail image. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
* `medium` – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
* `high` – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
* `standard` – An even higher resolution version of the thumbnail image than the `high` resolution image. This image is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 640px wide and 480px tall.
* `maxres` – The highest resolution version of the thumbnail image. This image size is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 1280px wide and 720px tall. | | `snippet.thumbnails.(key).url` | `string`
The image's URL. | | `snippet.thumbnails.(key).width` | `unsigned integer`
The image's width. | | `snippet.thumbnails.(key).height` | `unsigned integer`
The image's height. | | `snippet.channelTitle` | `string`
The title of the channel that published the resource that the search result identifies. | | `snippet.liveBroadcastContent` | `string`
An indication of whether a `video` or `channel` resource has live broadcast content. Valid property values are `upcoming`, `live`, and `none`.

For a `video` resource, a value of `upcoming` indicates that the video is a live broadcast that has not yet started, while a value of `live` indicates that the video is an active live broadcast. For a `channel` resource, a value of `upcoming` indicates that the channel has a scheduled broadcast that has not yet started, while a value of `live` indicates that the channel has an active live broadcast. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # I18nLanguages  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/i18nLanguages#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) I18nLanguages Stay organized with collections Save and categorize content based on your preferences. ==================================================================================================== An `**i18nLanguage**` resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location. A user could also manually select the desired UI language from the YouTube site footer. Each `i18nLanguage` resource identifies a language code and a name. The language code can be used as the value of the `hl` parameter when calling API methods like `videoCategories.list` and `guideCategories.list`. Methods ------- The API supports the following methods for `i18nLanguages` resources: [list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) Returns a list of application languages that the YouTube website supports. [Try it now](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#usage) . Resource representation ----------------------- The following JSON structure shows the format of a `i18nLanguages` resource: { "[kind](https://developers.google.com/youtube/v3/docs/i18nLanguages#kind) ": "youtube#i18nLanguage", "[etag](https://developers.google.com/youtube/v3/docs/i18nLanguages#etag) ": etag, "[id](https://developers.google.com/youtube/v3/docs/i18nLanguages#id) ": string, "[snippet](https://developers.google.com/youtube/v3/docs/i18nLanguages#snippet) ": { "[hl](https://developers.google.com/youtube/v3/docs/i18nLanguages#snippet.hl) ": string, "[name](https://developers.google.com/youtube/v3/docs/i18nLanguages#snippet.name) ": string } } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#i18nLanguage`. | | `etag` | `etag`
The Etag of this resource. | | `id` | `string`
The ID that YouTube uses to uniquely identify the i18n language. | | `snippet` | `object`
The `snippet` object contains basic details about the i18n language, such as its language code and name. | | `snippet.hl` | `string`
A BCP-47 code that uniquely identifies a language. | | `snippet.name` | `string`
The name of the language as it is written in the language specified using the `i18nLanguage.list` method's `[hl](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#hl) ` parameter. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # PlaylistItems: insert  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/playlistItems/insert#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) PlaylistItems: insert Stay organized with collections Save and categorize content based on your preferences. ============================================================================================================ Adds a resource to a playlist. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. Common use cases ---------------- Request ------- ### HTTP request POST https://www.googleapis.com/youtube/v3/playlistItems ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication) ). | Scope | | --- | | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include.

The following list contains the `part` names that you can include in the parameter value:

* `contentDetails`
* `id`
* `snippet`
* `status` | | **Optional parameters** | | | | `onBehalfOfContentOwner` | `string`
This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication)
. **Note:** This parameter is intended exclusively for YouTube content partners.

The `**onBehalfOfContentOwner**` parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Provide a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the request body. For that resource: * You must specify a value for these properties: * `snippet.playlistId` * `snippet.resourceId` * You can set values for these properties: * `snippet.playlistId` * `snippet.position` * `snippet.resourceId` * `contentDetails.note` * `contentDetails.startAt` * `contentDetails.endAt` Response -------- If successful, this method returns a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the response body. Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `forbidden (403)` | `playlistContainsMaximumNumberOfVideos` | The playlist already contains the maximum allowed number of items. | | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to insert the specified playlist item. | | `invalidValue (400)` | `invalidContentDetails` | The `contentDetails` property in the request is not valid. A possible reason is that `contentDetails.note` field is longer than 280 characters. | | `invalidValue (400)` | `invalidPlaylistItemPosition` | The request attempts to set the playlist item's position to an invalid or unsupported value. Check the value of the `position` property in the resource's `snippet`. | | `invalidValue (400)` | `invalidResourceType` | The `type` specified for the resource ID is not supported for this operation. The resource ID identifies the item being added to the playlist – e.g. `youtube#video`. | | `invalidValue (400)` | `manualSortRequired` | The request attempts to set the playlist item's position, but the playlist does not use manual sorting. (For example, playlist items might be sorted by date or popularity.) You can address the error by removing the `snippet.position` element from the resource that the request is inserting. If you want the playlist item to have a particular position in the list, you need to first update the playlist's **Ordering** option to **Manual** in the playlist's settings. This settings can be adjusted in the [YouTube Video Manager](https://www.youtube.com/view_all_playlists)
. | | `invalidValue (400)` | `videoAlreadyInAnotherSeriesPlaylist` | The video that you are trying to add to the playlist is already in another series playlist. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `notFound (404)` | `videoNotFound` | The video that you are trying to add to the playlist cannot be found. Check the value of the `videoId` property to ensure that it is correct. | | `required (400)` | `channelIdRequired` | The request does not specify a value for the required `channelId` property. | | `required (400)` | `playlistIdRequired` | The request does not specify a value for the required `playlistId` property. | | `required (400)` | `resourceIdRequired` | The request must contain a resource in which the `snippet` object specifies a `resourceId`. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to insert videos into the specified playlist. For example, you can't insert a video into your uploaded videos playlist. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Subscriptions  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/subscriptions#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Subscriptions Stay organized with collections Save and categorize content based on your preferences. ==================================================================================================== A `**subscription**` resource contains information about a YouTube user subscription. A subscription notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video. Methods ------- The API supports the following methods for `subscriptions` resources: [list](https://developers.google.com/youtube/v3/docs/subscriptions/list) Returns subscription resources that match the API request criteria. [Try it now](https://developers.google.com/youtube/v3/docs/subscriptions/list#usage) . [insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert) Adds a subscription for the authenticated user's channel. [Try it now](https://developers.google.com/youtube/v3/docs/subscriptions/insert#usage) . [delete](https://developers.google.com/youtube/v3/docs/subscriptions/delete) Deletes a subscription. [Try it now](https://developers.google.com/youtube/v3/docs/subscriptions/delete#usage) . Resource representation ----------------------- The following JSON structure shows the format of a `subscriptions` resource: { "[kind](https://developers.google.com/youtube/v3/docs/subscriptions#kind) ": "youtube#subscription", "[etag](https://developers.google.com/youtube/v3/docs/subscriptions#etag) ": etag, "[id](https://developers.google.com/youtube/v3/docs/subscriptions#id) ": string, "[snippet](https://developers.google.com/youtube/v3/docs/subscriptions#snippet) ": { "[publishedAt](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.publishedAt) ": datetime, "[channelTitle](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.channelTitle) ": string, "[title](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.description) ": string, "[resourceId](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.resourceId) ": { "[kind](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.resourceId.kind) ": string, "[channelId](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.resourceId.channelId) ": string, }, "[channelId](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.channelId) ": string, "[thumbnails](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.thumbnails) ": { (key): { "[url](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.thumbnails.(key).url) ": string, "[width](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.thumbnails.(key).width) ": unsigned integer, "[height](https://developers.google.com/youtube/v3/docs/subscriptions#snippet.thumbnails.(key).height) ": unsigned integer } } }, "[contentDetails](https://developers.google.com/youtube/v3/docs/subscriptions#contentDetails) ": { "[totalItemCount](https://developers.google.com/youtube/v3/docs/subscriptions#contentDetails.totalItemCount) ": unsigned integer, "[newItemCount](https://developers.google.com/youtube/v3/docs/subscriptions#contentDetails.newItemCount) ": unsigned integer, "[activityType](https://developers.google.com/youtube/v3/docs/subscriptions#contentDetails.activityType) ": string }, "[subscriberSnippet](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet) ": { "[title](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.description) ": string, "[channelId](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.channelId) ": string, "[thumbnails](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.thumbnails) ": { (key): { "[url](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.thumbnails.(key).url) ": string, "[width](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.thumbnails.(key).width) ": unsigned integer, "[height](https://developers.google.com/youtube/v3/docs/subscriptions#subscriberSnippet.thumbnails.(key).height) ": unsigned integer } } } } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#subscription`. | | `etag` | `etag`
The Etag of this resource. | | `id` | `string`
The ID that YouTube uses to uniquely identify the subscription. | | `snippet` | `object`
The `snippet` object contains basic details about the subscription, including its title and the channel that the user subscribed to. | | `snippet.publishedAt` | `datetime`
The date and time that the subscription was created. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime)
format. | | `snippet.title` | `string`
The subscription's title. | | `snippet.description` | `string`
The subscription's details. | | `snippet.resourceId` | `object`
The `id` object contains information about the channel that the user subscribed to. | | `snippet.resourceId.kind` | `string`
The type of the API resource. | | `snippet.resourceId.channelId` | `string`
The value that YouTube uses to uniquely identify the channel that the user subscribed to. | | `snippet.channelId` | `string`
The ID that YouTube uses to uniquely identify the subscriber's channel. The `resource_id` object identifies the channel that the user subscribed to. | | `snippet.thumbnails` | `object`
A map of thumbnail images associated with the subscription. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail. | | `snippet.thumbnails.(key)` | `object`
Valid key values are:

* `default` – The default thumbnail image for this resource. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
* `medium` – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
* `high` – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall. | | `snippet.thumbnails.(key).url` | `string`
The image's URL. | | `snippet.thumbnails.(key).width` | `unsigned integer`
The image's width. | | `snippet.thumbnails.(key).height` | `unsigned integer`
The image's height. | | `contentDetails` | `object`
The `contentDetails` object contains basic statistics about the subscription. | | `contentDetails.totalItemCount` | `unsigned integer`
The approximate number of items that the subscription points to. | | `contentDetails.newItemCount` | `unsigned integer`
The number of new items in the subscription since its content was last read. | | `contentDetails.activityType` | `string`
The type of activity this subscription is for (only uploads, everything).

Valid values for this property are:

* `all`
* `uploads` | | `subscriberSnippet` | `object`
The `subscriberSnippet` object contains basic details about the subscriber. | | `subscriberSnippet.title` | `string`
The title of the subscriber's channel. | | `subscriberSnippet.description` | `string`
The description of the subscriber's channel. | | `subscriberSnippet.channelId` | `string`
The ID that YouTube assigns to uniquely identify the subscriber's channel. | | `subscriberSnippet.thumbnails` | `object`
Thumbnail images for the subscriber's channel. | | `subscriberSnippet.thumbnails.(key)` | `object`
Valid key values are:

* `default` – The default thumbnail image for this resource. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
* `medium` – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
* `high` – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall. | | `subscriberSnippet.thumbnails.(key).url` | `string`
The image's URL. | | `subscriberSnippet.thumbnails.(key).width` | `unsigned integer`
The image's width. | | `subscriberSnippet.thumbnails.(key).height` | `unsigned integer`
The image's height. | Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # VideoCategories: list  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/videoCategories/list#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Français * Indonesia * Português – Brasil * Русский * 中文 – 简体 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) VideoCategories: list Stay organized with collections Save and categorize content based on your preferences. ============================================================================================================ Returns a list of categories that can be associated with YouTube videos. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. Common use cases ---------------- Request ------- ### HTTP request GET https://www.googleapis.com/youtube/v3/videoCategories ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters | | | --- | --- | | **Required parameters** | | | | `part` | `string`
The `**part**` parameter specifies the `videoCategory` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Filters (specify exactly one of the following parameters)** | | | | `id` | `string`
The `**id**` parameter specifies a comma-separated list of video category IDs for the resources that you are retrieving. | | `regionCode` | `string`
The `**regionCode**` parameter instructs the API to return the list of video categories available in the specified country. The parameter value is an [ISO 3166-1 alpha-2](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm)
country code. | | **Optional parameters** | | | | `hl` | `string`
The `**hl**` parameter specifies the language that should be used for text values in the API response. The default value is `en_US`. | ### Request body Do not provide a request body when calling this method. Response -------- If successful, this method returns a response body with the following structure: { "kind": "youtube#videoCategoryListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": \[\ [videoCategory resource](https://developers.google.com/youtube/v3/docs/videoCategories#resource)\ \] } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#videoCategoryListResponse`. | | `etag` | `etag`
The Etag of this resource. | | `nextPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string`
The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object`
The `pageInfo` object encapsulates paging information for the result set. | | `pageInfo.totalResults` | `integer`
The total number of results in the result set. | | `pageInfo.resultsPerPage` | `integer`
The number of results included in the API response. | | `items[]` | `list`
A list of video categories that can be associated with YouTube videos. In this map, the video category ID is the map key, and its value is the corresponding `videoCategory` resource. | Errors ------ The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | | --- | --- | --- | | `notFound (404)` | `videoCategoryNotFound` | The video category identified by the `id` parameter cannot be found. Use the [videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list)
method to retrieve a list of valid values. | Try it! ------- Use the APIs Explorer to call this API and see the API request and response. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/) , and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0) . For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2025-08-28 UTC. --- # Playlists  |  YouTube Data API  |  Google for Developers [Skip to main content](https://developers.google.com/youtube/v3/docs/playlists#main-content) [![YouTube](https://developers.google.com/static/site-assets/logo-youtube.svg)](https://developers.google.com/youtube) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) / * English * Deutsch * Español * Español – América Latina * Français * Indonesia * Italiano * Polski * Português – Brasil * Tiếng Việt * Türkçe * Русский * עברית * العربيّة * فارسی * हिंदी * বাংলা * ภาษาไทย * 中文 – 简体 * 中文 – 繁體 * 日本語 * 한국어 Sign in * [Home](https://developers.google.com/) * [Products](https://developers.google.com/products) * [YouTube](https://developers.google.com/youtube) * [Data API](https://developers.google.com/youtube/v3) * [Reference](https://developers.google.com/youtube/v3/docs) Playlists Stay organized with collections Save and categorize content based on your preferences. ================================================================================================ A `**playlist**` resource represents a YouTube playlist. A playlist is a collection of videos that can be viewed sequentially and shared with other users. By default, playlists are publicly visible to other users, but playlists can be public or private. YouTube also uses playlists to identify special collections of videos for a channel, such as: * uploaded videos * positively rated (liked) videos To be more specific, these lists are associated with a channel, which is a collection of a person, group, or company's videos, playlists, and other YouTube information. You can retrieve the playlist IDs for each of these lists from the `[channel resource](https://developers.google.com/youtube/v3/docs/channels) ` for a given channel. You can then use the `[playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) ` method to retrieve any of those lists. You can also add or remove items from those lists by calling the `[playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) ` and `[playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) ` methods. Methods ------- The API supports the following methods for `playlists` resources: [list](https://developers.google.com/youtube/v3/docs/playlists/list) Returns a collection of playlists that match the API request parameters. For example, you can retrieve all playlists that the authenticated user owns, or you can retrieve one or more playlists by their unique IDs. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/list#usage) . [insert](https://developers.google.com/youtube/v3/docs/playlists/insert) Creates a playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/insert#usage) . [update](https://developers.google.com/youtube/v3/docs/playlists/update) Modifies a playlist. For example, you could change a playlist's title, description, or privacy status. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/update#usage) . [delete](https://developers.google.com/youtube/v3/docs/playlists/delete) Deletes a playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/delete#usage) . Resource representation ----------------------- The following JSON structure shows the format of a `playlists` resource: { "[kind](https://developers.google.com/youtube/v3/docs/playlists#kind) ": "youtube#playlist", "[etag](https://developers.google.com/youtube/v3/docs/playlists#etag) ": etag, "[id](https://developers.google.com/youtube/v3/docs/playlists#id) ": string, "[snippet](https://developers.google.com/youtube/v3/docs/playlists#snippet) ": { "[publishedAt](https://developers.google.com/youtube/v3/docs/playlists#snippet.publishedAt) ": datetime, "[channelId](https://developers.google.com/youtube/v3/docs/playlists#snippet.channelId) ": string, "[title](https://developers.google.com/youtube/v3/docs/playlists#snippet.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/playlists#snippet.description) ": string, "[thumbnails](https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails) ": { (key): { "[url](https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).url) ": string, "[width](https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).width) ": unsigned integer, "[height](https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).height) ": unsigned integer } }, "[channelTitle](https://developers.google.com/youtube/v3/docs/playlists#snippet.channelTitle) ": string, "[defaultLanguage](https://developers.google.com/youtube/v3/docs/playlists#snippet.defaultLanguage) ": string, "[localized](https://developers.google.com/youtube/v3/docs/playlists#snippet.localized) ": { "[title](https://developers.google.com/youtube/v3/docs/playlists#snippet.localized.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/playlists#snippet.localized.description) ": string } }, "[status](https://developers.google.com/youtube/v3/docs/playlists#status) ": { "[privacyStatus](https://developers.google.com/youtube/v3/docs/playlists#status.privacyStatus) ": string, "[podcastStatus](https://developers.google.com/youtube/v3/docs/playlists#status.podcastStatus) ": enum }, "[contentDetails](https://developers.google.com/youtube/v3/docs/playlists#contentDetails) ": { "[itemCount](https://developers.google.com/youtube/v3/docs/playlists#contentDetails.itemCount) ": unsigned integer }, "[player](https://developers.google.com/youtube/v3/docs/playlists#player) ": { "[embedHtml](https://developers.google.com/youtube/v3/docs/playlists#player.embedHtml) ": string }, "[localizations](https://developers.google.com/youtube/v3/docs/playlists#localizations) ": { (key): { "[title](https://developers.google.com/youtube/v3/docs/playlists#localizations.title) ": string, "[description](https://developers.google.com/youtube/v3/docs/playlists#localizations.description) ": string } } } ### Properties The following table defines the properties that appear in this resource: | Properties | | | --- | --- | | `kind` | `string`
Identifies the API resource's type. The value will be `youtube#playlist`. | | `etag` | `etag`
The Etag of this resource. | | `id` | `string`
The ID that YouTube uses to uniquely identify the playlist. | | `snippet` | `object`
The `snippet` object contains basic details about the playlist, such as its title and description. | | `snippet.publishedAt` | `datetime`
The date and time that the playlist was created. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime)
format. | | `snippet.channelId` | `string`
The ID that YouTube uses to uniquely identify the channel that published the playlist. | | `snippet.title` | `string`
The playlist's title. | | `snippet.description` | `string`
The playlist's description. | | `snippet.thumbnails` | `object`
A map of thumbnail images associated with the playlist. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail. | | `snippet.thumbnails.(key)` | `object`
Valid key values are:

* `default` – The default thumbnail image. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
* `medium` – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
* `high` – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
* `standard` – An even higher resolution version of the thumbnail image than the `high` resolution image. This image is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 640px wide and 480px tall.
* `maxres` – The highest resolution version of the thumbnail image. This image size is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 1280px wide and 720px tall. | | `snippet.thumbnails.(key).url` | `string`
The image's URL. | | `snippet.thumbnails.(key).width` | `unsigned integer`
The image's width. | | `snippet.thumbnails.(key).height` | `unsigned integer`
The image's height. | | `snippet.channelTitle` | `string`
The channel title of the channel that the video belongs to. | | `snippet.tags[]` | `list`
This property has been deprecated.

Keyword tags associated with the playlist. | | `snippet.defaultLanguage` | `string`
The language of the text in the `playlist` resource's `snippet.title` and `snippet.description` properties. | | `snippet.localized` | `object`
The `snippet.localized` object contains either a localized title and description for the playlist or the title in the [default language](https://developers.google.com/youtube/v3/docs/playlists#snippet.defaultLanguage)
for the playlist's metadata.

* Localized text is returned in the resource snippet if the `[playlists.list](https://developers.google.com/youtube/v3/docs/playlists/list) ` request used the `hl` parameter to specify a language for which localized text should be returned _and_ localized text is available in that language.
* Metadata for the default language is returned if an `hl` parameter value is not specified _or_ a value is specified but localized metadata is not available for the specified language.

The property contains a read-only value. Use the `[localizations](https://developers.google.com/youtube/v3/docs/playlists#localizations) ` object to add, update, or delete localized titles. | | `snippet.localized.title` | `string`
The localized playlist title. | | `snippet.localized.description` | `string`
The localized playlist description. | | `status` | `object`
The `status` object contains status information for the playlist. | | `status.privacyStatus` | `string`
The playlist's privacy status.

Valid values for this property are:

* `private`
* `public`
* `unlisted` | | `status.podcastStatus` | `string`
The playlist's podcast status. If value is `enabled`, the playlist is marked as a podcast show. To set a playlist's podcast status to `enabled`, the playlist must have a [playlist image](https://developers.google.com/youtube/v3/docs/playlistImages/insert)
.

Valid values for this property are:

* `enabled`
* `disabled`
* `unspecified` | | `contentDetails` | `object`
The `contentDetails` object contains information about the playlist content, including the number of videos in the playlist. | | `contentDetails.itemCount` | `unsigned integer`
The number of videos in the playlist. | | `player` | `object`
The `player` object contains information that you would use to play the playlist in an embedded player. | | `player.embedHtml` | `string`
An `