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/[Playlist ID]/items?X-Plex-Token=[PlexToken]
Parameters
| Name | Description |
|---|---|
| IP address | The IP address of the Plex Media server. |
| PlexToken | The temporary authentication Plex token. |
| Playlist ID | The 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 Code | Description |
|---|---|
| 200 | Success - The request was successful. |
| 401 | Unauthorized - The Plex token provided was not valid. |
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>
Remarks
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.
| Attribute | Description |
|---|---|
| size | The number of playlists returned for the playlist ID. |
| composite | The URL of the composite image used for the playlist. |
| duration | Total time in milliseconds for all items in the playlist. This attribute is not available for photo playlists. |
| leafCount | Total items in the playlist. |
| playlistType | The type media in the playlist. |
| ratingKey | The unique ID for the playlist. |
| smart | 1 - playlist is a smart playlist. 0 - playlist is not a smart playlist. |
| title | The name 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.
| Attribute | Description |
|---|---|
| ratingKey | A key associated with the movie. |
| key | The relative URL of the movie information. |
| guid | The unique identifier comprised of the Plex agent and movie identifier for the agent. |
| studio | The name of the movie studio. |
| type | The type of media. |
| title | The title of the movie. |
| titleSort | The title of the movie used to sort the movie in a collection or list. |
| librarySectionTitle | The name of the library section where the item is located. |
| librarySectionID | The ID of the library section. |
| librarySectionKey | The relative URL of the library section. |
| contentRating | The content rating associated with the movie. |
| summary | A summary of the movie. |
| rating | The rating for the movie. |
| audienceRating | The audience rating for the movie. |
| viewCount | The number of times the item was viewed. |
| lastViewedAt | The date and time value when the item was last viewed. |
| year | The year the movie was released. |
| thumb | The thumbnail for the movie. |
| art | The background artwork used to represent the movie. |
| duration | The length of the movie in milliseconds. |
| originallyAvailableAt | The original release date of the movie. |
| addedAt | The date and time the movie was added to the library. |
| updatedAt | The date and time the movie was updated in the library. |
| chapterSource | The 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.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the media. |
| duration | The length of the media in milliseconds. |
| bitrate | The bitrate of the media. |
| width | The width of the media. |
| height | The height of the media. |
| aspectRatio | The aspect ratio of the media. |
| audioChannels | The number of audio channels. |
| audioCodec | The codec used for the audio. |
| videoCodec | The codec used for the video. |
| videoResolution | The resolution used for the video. |
| container | The container for the media. |
| videoFrameRate | The frame rate for the video. |
| audioProfile | The frame rate for the video. |
| videoProfile | The 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.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the part. |
| key | The unique relative path for the part that is used at its key. |
| duration | The length of the part in milliseconds. |
| file | The file associated with the part. |
| size | The file size of the part. |
| audioProfile | The frame rate for the video. |
| container | The type of media container. |
| videoProfile | The video profile associated with the movie 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.
Music Playlists
Within the MediaContainer there is one or more Track child elements that contain the details about the music items in the playlist.
| Attribute | Description |
|---|---|
| ratingKey | A key associated with the track. |
| key | The relative URL of the music information track. |
| parentRatingKey | The relative URL of the information for the parent item. |
| grandparentRatingKey | The relative URL of the information for the grandparent item. |
| guid | The GUID for the track. |
| parentGuid | The GUID for the parent item. |
| grandparentGuid | The GUID for the grandparent item. |
| parentStudio | The name of the studio for the parent. |
| type | The type of item. |
| title | The name of the track. |
| grandparentKey | The unique identifier for the grandparent item. |
| parentKey | The unique identifier for the parent item. |
| librarySectionTitle | The name of the library section that contains the item. |
| librarySectionID | The unique identifier of the library section that contains the item. |
| librarySectionKey | The relative URL of the library section that contains the item. |
| grandparentTitle | The name of the grandparent item |
| parentTitle | The name of the parent item |
| summary | A summary of the track. |
| index | Unknown. |
| parentIndex | Unknown. |
| ratingCount | A count of the rating. |
| parentYear | The year the parent item was released. |
| thumb | The thumbnail for the track. |
| art | The background artwork used to represent the track. |
| parentThumb | The thumbnail for the parent item. |
| grandparentThumb | The thumbnail for the grandparent item. |
| grandparentArt | The background artwork used to represent the grandparent. |
| duration | The duration in milliseconds of the track. |
| addedAt | The date and time the music track was added to the library. |
| updatedAt | The date and time the music 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.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the track. |
| duration | The length of the track in milliseconds. |
| bitrate | The bitrate of the track. |
| audioChannels | The number of audio channels. |
| audioCodec | The codec used for the audio. |
| container | The container for the media. |
Within the Media there are one or more Part child elements.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the part. |
| key | The unique relative path for the part that is used at its key. |
| duration | The length of the part in milliseconds. |
| file | The file associated with the part. |
| size | The file size of the part. |
| container | The 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.
| Attribute | Description |
|---|---|
| ratingKey | A key associated with the photo. |
| key | The relative URL of the music information photo. |
| parentRatingKey | The relative URL of the information for the parent item. |
| grandparentRatingKey | The relative URL of the information for the grandparent item. |
| guid | The GUID for the photo. |
| parentGuid | The GUID for the parent item. |
| grandparentGuid | The GUID for the grandparent item. |
| type | The type of item. |
| title | The name of the photo. |
| grandparentKey | The unique identifier for the grandparent item. |
| parentKey | The unique identifier for the parent item. |
| librarySectionTitle | The name of the library section that contains the item. |
| librarySectionID | The unique identifier of the library section that contains the item. |
| librarySectionKey | The relative URL of the library section that contains the item. |
| grandparentTitle | The name of the grandparent item |
| parentTitle | The name of the parent item |
| summary | A summary of the photo. |
| index | Unknown. |
| parentIndex | Unknown. |
| parentYear | The year the parent item was taken. |
| thumb | The thumbnail for the photo. |
| art | The background artwork used to represent the photo. |
| parentThumb | The thumbnail for the parent item. |
| grandparentThumb | The thumbnail for the grandparent item. |
| grandparentArt | The background artwork used to represent the grandparent. |
| playlistItemID | The unique ID of the item in the playlist. |
| originallyAvailableAt | The original date of the photo. |
| addedAt | The date and time the photo was added to the library. |
| updatedAt | The date and time the photo was updated in the library. |
Within the Photo there are one or more Media child elements.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the track. |
| width | The width, in pixels, of the photo.. |
| height | The bheight, in pixels, of the photo. |
| aspectRatio | The aspect ratio of the photo. |
| container | The container for the photo. |
Within the Media there are one or more Part child elements.
| Attribute | Description |
|---|---|
| id | Unique ID associated with the part. |
| key | The unique relative path for the part that is used at its key. |
| file | The file associated with the part. |
| size | The file size of the part. |
| container | The type of media container. |
| orientation | 1 - photo is in landscape. 8 - photo is in portrait. |
Examples
Example 1
Gets the playlist information for the playlist associated with ID 279065 on the Plex Media Server located at the IP address of 192.168.1.4:
GET http://192.168.1.4:32400/playlists/279065/?X-Plex-Token=L6vkd7JtLHjsH5987vYY