A playlist resource represents a YouTube playlist. A playlist is a collection of videos that can be viewed sequentially and shared with other users. A playlist can contain up to 200 videos, and YouTube does not limit the number of playlists that each user creates. 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
  • favorite 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 for a given channel.

You can then use the playlistItems.list method to retrieve any of those lists. You can also add or remove items from those lists by calling the playlistItems.insert and playlistItems.delete methods.


The API supports the following methods for playlists resources:

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.
Creates a playlist. Try it now.
Modifies a playlist. For example, you could change a playlist's title, description, or privacy status. Try it now.
Deletes a playlist. Try it now.

Resource representation

The JSON structure below shows the format of a playlists resource:

  "kind": "youtube#playlist",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
    "channelTitle": string,
    "tags": [
  "status": {
    "privacyStatus": string
  "contentDetails": {
    "itemCount": unsigned integer
  "player": {
    "embedHtml": string


The following table defines the properties that appear in this resource:

Property name Value Description
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 (YYYY-MM-DDThh:mm:ss.sZ) 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 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.
snippet.channelTitle string The channel title of the channel that the video belongs to.
snippet.tags[] list Keyword tags associated with the playlist.
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
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 <iframe> tag that embeds a player that will play the playlist.