List

Returns a collection of playlist items that match the API request parameters

7 variables
36 variables

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

Authorization

To use this building block you will have to grant access to at least one of the following scopes:

  • Manage your YouTube account
  • See, edit, and permanently delete your YouTube videos, ratings, comments and captions
  • View your YouTube account
  • View and manage your assets and associated content on YouTube

Input

This building block consumes 7 input parameters

  = Parameter name
  = Format

part STRING Required

The part parameter specifies a comma-separated list of one or more playlistItem 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 playlistItem resource, the snippet property contains numerous fields, including the title, description, position, and resourceId properties. As such, if you set part=snippet, the API response will contain all of those properties

id STRING

The id parameter specifies a comma-separated list of one or more unique playlist item IDs

maxResults INTEGER

The maxResults parameter specifies the maximum number of items that should be returned in the result set

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

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

playlistId STRING

The playlistId parameter specifies the unique ID of the playlist for which you want to retrieve playlist items. Note that even though this is an optional parameter, every request to retrieve playlist items must specify a value for either the id parameter or the playlistId parameter

videoId STRING

The videoId parameter specifies that the request should return only the playlist items that contain the specified video

Output

This building block provides 36 output parameters

  = Parameter name
  = Format

etag STRING

Etag of this resource

eventId STRING

Serialized EventId of the request which produced this response

items[] OBJECT

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 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. For example, if a user gives a positive rating to a video, you would insert that video into the liked videos playlist for that user's channel

items[].contentDetails OBJECT

items[].contentDetails.endAt STRING

The time, measured in seconds from the start of the video, when the video should stop playing. (The playlist owner can specify the times when the video should start and stop playing when the video is played in the context of the playlist.) By default, assume that the video.endTime is the end of the video

items[].contentDetails.note STRING

A user-generated note for this item

items[].contentDetails.startAt STRING

The time, measured in seconds from the start of the video, when the video should start playing. (The playlist owner can specify the times when the video should start and stop playing when the video is played in the context of the playlist.) The default value is 0

items[].contentDetails.videoId STRING

The ID that YouTube uses to uniquely identify a video. To retrieve the video resource, set the id query parameter to this value in your API request

items[].contentDetails.videoPublishedAt DATE_TIME

The date and time that the video was published to YouTube. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format

items[].etag STRING

Etag of this resource

items[].id STRING

The ID that YouTube uses to uniquely identify the playlist item

items[].kind STRING

Identifies what kind of resource this is. Value: the fixed string "youtube#playlistItem"

items[].snippet OBJECT

Basic details about a playlist, including title, description and thumbnails

items[].snippet.channelId STRING

The ID that YouTube uses to uniquely identify the user that added the item to the playlist

items[].snippet.channelTitle STRING

Channel title for the channel that the playlist item belongs to

items[].snippet.description STRING

The item's description

items[].snippet.playlistId STRING

The ID that YouTube uses to uniquely identify the playlist that the playlist item is in

items[].snippet.position INTEGER

The order in which the item appears in the playlist. The value uses a zero-based index, so the first item has a position of 0, the second item has a position of 1, and so forth

items[].snippet.publishedAt DATE_TIME

The date and time that the item was added to the playlist. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format

items[].snippet.resourceId OBJECT

A resource id is a generic reference that points to another YouTube resource

items[].snippet.resourceId.channelId STRING

The ID that YouTube uses to uniquely identify the referred resource, if that resource is a channel. This property is only present if the resourceId.kind value is youtube#channel

items[].snippet.resourceId.kind STRING

The type of the API resource

items[].snippet.resourceId.playlistId STRING

The ID that YouTube uses to uniquely identify the referred resource, if that resource is a playlist. This property is only present if the resourceId.kind value is youtube#playlist

items[].snippet.resourceId.videoId STRING

The ID that YouTube uses to uniquely identify the referred resource, if that resource is a video. This property is only present if the resourceId.kind value is youtube#video

items[].snippet.thumbnails OBJECT

Internal representation of thumbnails for a YouTube resource

items[].snippet.title STRING

The item's title

items[].status OBJECT

Information about the playlist item's privacy status

items[].status.privacyStatus ENUMERATION

This resource's privacy status

kind STRING

Identifies what kind of resource this is. Value: the fixed string "youtube#playlistItemListResponse"

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

Paging details for lists of resources, including total number of items available and number of resources returned in a single page

pageInfo.resultsPerPage INTEGER

The number of results included in the API response

pageInfo.totalResults INTEGER

The total number of results 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

tokenPagination OBJECT

Stub token pagination template to suppress results

visitorId STRING

The visitorId identifies the visitor