View Items in a Playlist

Each playlist that is created on a Plex server contains different media files. Each playlist can contain only one type of file, but can contain hundreds of the same media type.

This API command will return the details of all items that are associated with a specific playlist.

URL

GET http://{ip_address}:32400/playlists/{id}/items?X-Plex-Token={plex_token}

Parameters

NameDescription
ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex user token.
idThe key associated with a playlist. This key can be found by calling the view playlists for a user API command and getting the value in the ratingsKey attribute.

Return Status

HTTP CodeDescription
200Success - The request was successful.
401Unauthorized - The Plex token provided was not valid.
404Not Found - The playlist associated with the ID was not found.

Response

XML string value that lists the all the items in a playlist. The XML return is dependent on the type of media that is contained in the playlist.

For movie playlists, an example XML returned is:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="22" composite="/playlists/279065/composite/1649882407" duration="150764" leafCount="22" playlistType="video" ratingKey="279065" smart="1" title="1980's Movies">
    <Video ratingKey="279061" key="/library/metadata/279061" guid="com.plexapp.agents.imdb://tt0088763?lang=en" studio="Universal Pictures" type="movie" title="Back to the Future" titleSort="Back to the Future 1" librarySectionTitle="Movies" librarySectionID="2" librarySectionKey="/library/sections/2" contentRating="PG" summary="Marty McFly, a typical American teenager of the Eighties, is accidentally sent back to 1955 in a plutonium-powered DeLorean "time machine" invented by a slightly mad scientist. During his often hysterical, always amazing trip back in time, Marty must make certain his teenage parents-to-be meet and fall in love - so he can get back to the future." rating="8.5" viewCount="1" lastViewedAt="1533441384" year="1985" tagline="He's the only kid ever to get into trouble before he was born." thumb="/library/metadata/279061/thumb/1649456734" art="/library/metadata/279061/art/1649456734" duration="6964469" originallyAvailableAt="1985-07-02" addedAt="1649456672" updatedAt="1649456734" chapterSource="media">
        <Media id="338432" duration="6964469" bitrate="3285" width="720" height="460" aspectRatio="1.85" audioChannels="6" audioCodec="ac3" videoCodec="h264" videoResolution="sd" container="mkv" videoFrameRate="NTSC" videoProfile="high">
            <Part id="338785" key="/library/parts/338785/1464487773/file.mkv" duration="6964469" file="M:\Media\Movies\Back to the Future (1985)\Back to the Future (1985) [480p h.264][AAC AC3].mkv" size="2865442785" container="mkv" videoProfile="high" />
        </Media>
        <Genre tag="Adventure" />
        <Genre tag="Comedy" />
        <Country tag="USA" />
        <Collection tag="Back to the Future" />
    </Video>
    ...
</MediaContainer>

For music playlists, an example XML returned is:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="1096" composite="/playlists/275025/composite/1647266136" duration="268843" leafCount="1096" playlistType="audio" ratingKey="275025" smart="1" title="All Music">
    <Track ratingKey="218550" key="/library/metadata/218550" parentRatingKey="218549" grandparentRatingKey="218548" guid="plex://track/5d07cdc7403c640290f6a452" parentGuid="plex://album/5d07c182403c64029084e584" grandparentGuid="plex://artist/5d07bbfd403c6402904a6593" parentStudio="Polydor" type="track" title="Dancing Queen" grandparentKey="/library/metadata/218548" parentKey="/library/metadata/218549" librarySectionTitle="Music" librarySectionID="8" librarySectionKey="/library/sections/8" grandparentTitle="ABBA" parentTitle="Gold: Greatest Hits" summary="" index="1" parentIndex="1" ratingCount="1134970" parentYear="1992" thumb="/library/metadata/218549/thumb/1648794696" art="/library/metadata/218548/art/1649916521" parentThumb="/library/metadata/218549/thumb/1648794696" grandparentThumb="/library/metadata/218548/thumb/1649916521" grandparentArt="/library/metadata/218548/art/1649916521" duration="231400" addedAt="1598373482" updatedAt="1648794696">
        <Media id="278042" duration="231400" bitrate="978" audioChannels="2" audioCodec="flac" container="flac">
            <Part id="278372" key="/library/parts/278372/1598369723/file.flac" duration="231400" file="I:\Music\ABBA\Gold- Greatest Hits\01 Dancing Queen.flac" size="28310307" container="flac" />
        </Media>
    </Track>
    ...
</MediaContainer>        

For photo playlists, an example XML returned is:

    <?xml version="1.0" encoding="UTF-8"?>
    <MediaContainer size="1" composite="/playlists/279108/composite/1649881265" leafCount="1" playlistType="photo" ratingKey="279108" smart="0" title="Vacation">
        <Photo ratingKey="193259" key="/library/metadata/193259" parentRatingKey="3680" grandparentRatingKey="3663" guid="com.plexapp.agents.none://3681?lang=xn" parentGuid="local://3680" grandparentGuid="local://3663" type="photo" title="100-0001_CRW" grandparentKey="/library/metadata/3663" parentKey="/library/metadata/3680" librarySectionTitle="Photos" librarySectionID="1" librarySectionKey="/library/sections/1" grandparentTitle="2002" parentTitle="Mexico" summary="" index="1" parentIndex="1" year="2002" thumb="/library/metadata/193259/thumb/1492274439" art="/library/metadata/3680/art/1492274446" parentThumb="/library/metadata/3680/thumb/1492274446" grandparentThumb="/library/metadata/3663/thumb/1611751196" grandparentArt="/library/metadata/3663/art/1611751196" playlistItemID="11382" originallyAvailableAt="2002-11-08" addedAt="1430260595" updatedAt="1492274439" createdAtAccuracy="local" createdAtTZOffset="-18000">
            <Media id="252958" width="2312" height="1720" aspectRatio="1.33" container="raw">
                <Part id="253288" key="/library/parts/253288/1036805184/file.Crw" file="I:\Pictures\2002\Mexico\100-0001_CRW.Crw" size="2128044" container="raw" orientation="1" />
            </Media>
        </Photo>
        ...
    </MediaContainer>

The XML returned provides information about the items associated with the specified playlist ID. The root is the MediaContainer element. This element contains a few attributes that provide overall information about the items in the playlist.

MediaContainer Attributes
AttributeDescription
sizeThe number of items in the playlist.
compositeThe URL of the composite image used for the playlist.
durationTotal time in milliseconds for all items in the playlist. This attribute is not available for photo playlists.
leafCountTotal items in the playlist.
playlistTypeThe type of media in the playlist.
ratingKeyThe unique ID for the playlist.
smart1 - playlist is a smart playlist.
0 - playlist is not a smart playlist.
titleThe title of the playlist.

Movie Playlists

Within the MediaContainer there is one or more Video child elements that contain the details about the movie items in the playlist.

Video Attributes
AttributeDescription
ratingKeyA key associated with the movie.
keyThe relative URL of the movie information.
guidThe unique identifier comprised of the Plex agent and movie identifier for the agent.
studioThe name of the movie studio.
typeThe type of media.
titleThe title of the movie.
titleSortThe title of the movie used to sort the movies in a collection or list.
librarySectionTitleThe name of the library section where the movie is located.
librarySectionIDThe ID of the library section.
librarySectionKeyThe relative URL of the library section.
contentRatingThe content rating associated with the movie.
summaryA summary of the movie.
ratingThe rating for the movie.
audienceRatingThe audience rating for the movie.
viewCountThe number of times the movie has been viewed.
lastViewedAtThe date and time for the last time the movie was viewed.
yearThe year the movie was released.
thumbThe thumbnail for the movie.
artThe background artwork used to represent the movie.
playlistItemIDThe unique ID of the item in the playlist.
durationThe length of the movie in milliseconds.
originallyAvailableAtThe original release date of the movie.
addedAtThe date and time, in Unix time, the movie was added to the library.
updatedAtThe date and time in epoch time, the movie was updated in the library.
chapterSourceThe chapter source type.

Within the Video there are one or more Media child elements. Each Media element represents one media file of the movie available on the Plex server.

If there are two media files associated with the movie, such as a 1080p and 480p version, then there would be two Media child elements in the Video element.

Media Attributes
AttributeDescription
idUnique ID associated with the movie.
durationThe length of the movie in milliseconds.
bitrateThe bitrate of the movie.
widthThe width of the movie.
heightThe height of the movie.
aspectRatioThe aspect ratio of the movie.
audioChannelsThe number of audio channels.
audioCodecThe audio codec used to encode the audio.
videoCodecThe video codec used to encode the video.
videoResolutionThe video resolution.
containerThe movie container.
videoFrameRateThe framerate standard used for the video.
audioProfileThe audio profile of the media.
videoProfileThe video profile of the media.

Within the Media there are one or more Part child elements. Each Part element represents one part of the movie. If the movie has been added to the Plex server as a multi-part movie, then each of those parts will be represented by one Part child element.

Part Attributes
AttributeDescription
idUnique ID associated with the part.
keyThe unique relative path for the part that is used at its key.
durationThe length of the part in milliseconds.
fileThe file associated with the part.
sizeThe file size of the part.
audioProfileThe audio profile associated with the audio part.
containerThe type of media container.
videoProfileThe video profile associated with the video part.

Also within the Video element there are multiple additional child elements that provide more details about the movie. These child elements include Genre, Director, Writer, Country, Collection, and Role.

Within each of these child elements is a single tag attribute that provides the information for the element. There could be multiple of the same child element within the Video, such as multiple directors or writers.

Genre Attributes
AttributeDescription
tagA genre of the movie.
Director Attributes
AttributeDescription
tagA director of the movie.
Writer Attributes
AttributeDescription
tagA writer for the movie
Country Attributes
AttributeDescription
tagA country of origin for the movie.
Collection Attributes
AttributeDescription
tagThe name of a collection containing the movie.
Role Attributes
AttributeDescription
tagThe name of a person with a role in the movie.

Music Playlists

Within the MediaContainer there is one or more Track child elements that contain the details about the music items in the playlist.

The parent item for the tracks refers to the album that includes the track.

Track Attributes
AttributeDescription
ratingKeyA key associated with the track.
keyThe relative URL of the track information.
parentRatingKeyThe relative URL of the information for the album.
grandparentRatingKeyThe relative URL of the information for the artist.
guidThe unique identifier comprised of the Plex agent and track identifier for the agent.
parentGuidThe GUID for the album.
grandparentGuidThe GUID for the artist.
parentStudioThe name of the studio for the album.
typeThe type of media.
titleThe title of the track.
grandparentKeyThe unique identifier for the artist.
parentKeyThe unique identifier for the album.
librarySectionTitleThe name of the library section where the track is located.
librarySectionIDThe ID of the library section.
librarySectionKeyThe relative URL of the library section.
grandparentTitleThe title of the artist.
parentTitleThe title of the album.
summaryA summary of the track.
indexThe index of the track.
parentIndexThe index of the album.
ratingCountA count of the rating.
parentYearThe year the album was released.
thumbThe thumbnail for the track.
artThe background artwork used to represent the track.
parentThumbThe thumbnail for the album.
grandparentThumbThe thumbnail for the artist.
grandparentArtThe background artwork used to represent the artist.
durationThe length of the track in milliseconds.
addedAtThe date and time, in Unix time, the track was added to the library.
updatedAtThe date and time in epoch time, the track was updated in the library.

Within the Track there are one or more Media child elements. Each Media element represents one media file of the track available on the Plex server.

Media Attributes
AttributeDescription
idUnique ID associated with the track.
durationThe length of the track in milliseconds.
bitrateThe bitrate of the track.
audioChannelsThe number of audio channels.
audioCodecThe audio codec used to encode the audio.
containerThe track container.

Within the Media there are one or more Part child elements.

Part Attributes
AttributeDescription
idUnique ID associated with the part.
keyThe unique relative path for the part that is used at its key.
durationThe length of the part in milliseconds.
fileThe file associated with the part.
sizeThe file size of the part.
containerThe type of media container.

Photo Playlists

Within the MediaContainer there is one or more Photo child elements that contain the details about the photo items in the playlist.

Photo Attributes
AttributeDescription
ratingKeyA key associated with the photo.
keyThe relative URL of the photo information.
parentRatingKeyThe relative URL of the information for the parent.
grandparentRatingKeyThe relative URL of the information for the grandparent.
guidThe unique identifier comprised of the Plex agent and photo identifier for the agent.
parentGuidThe GUID for the parent.
grandparentGuidThe GUID for the grandparent.
typeThe type of media.
titleThe title of the photo.
grandparentKeyThe unique identifier for the grandparent.
parentKeyThe unique identifier for the parent.
librarySectionTitleThe name of the library section where the photo is located.
librarySectionIDThe ID of the library section.
librarySectionKeyThe relative URL of the library section.
grandparentTitleThe title of the grandparent.
parentTitleThe title of the parent.
summaryA summary of the photo.
indexThe index of the photo.
parentIndexThe index of the parent.
parentYearThe year the parent was released.
thumbThe thumbnail for the photo.
artThe background artwork used to represent the photo.
parentThumbThe thumbnail for the parent.
grandparentThumbThe thumbnail for the grandparent.
grandparentArtThe background artwork used to represent the grandparent.
playlistItemIDThe unique ID of the item in the playlist.
originallyAvailableAtThe original release date of the photo.
addedAtThe date and time, in Unix time, the photo was added to the library.
updatedAtThe date and time in epoch time, the photo was updated in the library.

Within the Photo there are one or more Media child elements.

Media Attributes
AttributeDescription
idUnique ID associated with the photo.
widthThe width of the photo.
heightThe height of the photo.
aspectRatioThe aspect ratio of the photo.
containerThe photo container.

Within the Media there are one or more Part child elements.

Part Attributes
AttributeDescription
idUnique ID associated with the part.
keyThe unique relative path for the part that is used at its key.
fileThe file associated with the part.
sizeThe file size of the part.
containerThe type of media container.
orientation1 - photo is in landscape.
8 - photo is in portrait.

Remarks

A playlist is specific to a user on the Plex server. Only that user can request information about a playlist.

When using a device Plex authentication token, the administrative user playlists will be returned by the Plex server. This means that the administrator's Plex token and any device token will return the same XML response.

Examples

curl -X GET http://{ip_address}:32400/playlists/{id}/items?X-Plex-Token={plex_token}
import requests
plex_url = http://{ip_address}:32400/playlists/{id}/items?X-Plex-Token={plex_token}
response = requests.get(plex_url)
print(response.text)
$response = Invoke-RestMethod 'http://{ip_address}:32400/playlists/{id}/items?X-Plex-Token={plex_token}' -Method 'GET'
Write-Output $response
Subscribe
Display