Get All TV Show Episodes

A TV show that has been added to Plex has multiple levels of information. A TV show contains a season and within each season, there could be one or more episodes. This API command returns all episodes for a season for a TV show.

URL

GET http://{ip_address}:32400/library/metadata/{id}/children?X-Plex-Token={plex_token}&includeGuids={include_guids}&{filter}

Parameters

NameDescription
ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex token.
idThe key associated with a TV show season. This key can be found by calling the Get All TV Show Seasons API command and looking for a ratingKey for the season.
include_guids(Optional) Returns the GUID values of the online metadata services associated to the media item.
filter(Optional) The filter to apply to the response.

Return Status

HTTP CodeDescription
200Success - The request was successful.
401Unauthorized - The Plex token provided was not valid.

Response

XML string value that lists the all the TV show episodes in the library. An example of the XML returned from the request is shown below:

<MediaContainer size="13" allowSync="1" art="/library/metadata/275479/art/1673348103" grandparentContentRating="TV-G" grandparentRatingKey="275479" grandparentStudio="WIPB" grandparentTheme="/library/metadata/275479/theme/1673348103" grandparentThumb="/library/metadata/275479/thumb/1673348103" grandparentTitle="The Joy of Painting" identifier="com.plexapp.plugins.library" key="275480" librarySectionID="4" librarySectionTitle="TV Shows" librarySectionUUID="3bbbe6f7-628f-4983-ae5d-7c05779c4c28" mediaTagPrefix="/system/bundle/media/flags/" mediaTagVersion="1677707382" nocache="1" parentIndex="1" parentTitle="The Joy of Painting" sortAsc="1" summary="Season 1 of The Joy of Painting with Bob Ross features the following wonderful painting instructions: A Walk in the Woods, Mt. McKinley, Ebony Sunset, Winter Mist, Quiet Stream, Winter Moon, Autumn Mountains, Peaceful Valley, Seascape, Mountain Lake, Winter Glow, and Snowfall." theme="/library/metadata/275479/theme/1673348103" thumb="/library/metadata/275480/thumb/1659190872" title1="The Joy of Painting" title2="The Joy of Painting" viewGroup="episode" viewMode="131133">
<Video ratingKey="275481" key="/library/metadata/275481" parentRatingKey="275480" grandparentRatingKey="275479" guid="plex://episode/5d9c12c8705e7a001e76391f" parentGuid="plex://season/602e683d88e0a9002df8a4ff" grandparentGuid="plex://show/5d9c086e3c3f87001f34fc00" type="episode" title="A Walk in the Woods" titleSort="Walk in the Woods" grandparentKey="/library/metadata/275479" parentKey="/library/metadata/275480" grandparentTitle="The Joy of Painting" parentTitle="The Joy of Painting" contentRating="TV-G" summary="Bob Ross introduces us to his "Almighty" assortment of tools and colors, tells us that anyone can paint, and creates a landscape of a forest path just after a rain shower." index="1" parentIndex="1" year="1983" thumb="/library/metadata/275481/thumb/1674982811" art="/library/metadata/275479/art/1673348103" parentThumb="/library/metadata/275480/thumb/1659190872" grandparentThumb="/library/metadata/275479/thumb/1673348103" grandparentArt="/library/metadata/275479/art/1673348103" grandparentTheme="/library/metadata/275479/theme/1673348103" duration="1681271" originallyAvailableAt="1983-01-11" addedAt="1619709963" updatedAt="1674982811">
    <Media id="334942" duration="1681271" bitrate="827" width="640" height="480" aspectRatio="1.33" audioChannels="2" audioCodec="aac" videoCodec="h264" videoResolution="480" container="mp4" videoFrameRate="NTSC" optimizedForStreaming="1" audioProfile="lc" has64bitOffsets="0" videoProfile="constrained baseline">
        <Part id="335274" key="/library/parts/335274/1619732910/file.mp4" duration="1681271" file="M:\Media\TV Shows\The Joy of Painting\Season 01\Bob Ross - The Joy of Painting - s01e01.mp4" size="175144278" audioProfile="lc" container="mp4" has64bitOffsets="0" optimizedForStreaming="1" videoProfile="constrained baseline" />
    </Media>
    <Role tag="Steve Ross" />
</Video>
    ...
</MediaContainer>

The XML returned provides a list of the episodes in a season that are available on the Plex server. The root is the MediaContainer element. This element contains a few attributes that provide overall information about the season's episodes on the server.

MediaContainer Attributes
AttributeDescription
sizeThe number of episodes.
allowSync1 - allow syncing content.
0 - don't allow syncing content.
artBackground artwork used to represent the episode.
grandparentContentRatingThe content rating for the TV show.
grandparentRatingKeyThe key associated with the TV show.
grandparentStudioThe studio associated with the TV show.
grandparentThemeThe theme associated with the TV show.
grandparentThumbThe thumbnail image associated with the TV show.
grandparentTitleThe title of the TV show.
identifierThe type of item.
keyUnique identifier for the episode.
librarySectionIDThe unique key associated with the library.
librarySectionTitleThe title of the library.
librarySectionUUIDUnique GUID identifier for the library.
mediaTagPrefixPrefix for the media tag.
mediaTagVersionMedia tag version.
Note: This could be a date and time value.
nocache1 - cache the library.
0 - do not cache the library.
parentIndexThe index of the season.
parentTitleThe title of the season.
sortAsc1 - the library is sorted in ascending order.
0 - the library is sorted in descending order.
summaryThe summary for the episode.
themeThe theme for the episode.
thumbThe thumbnail for the episode.
title1The title of the episode.
Note: This appears to be internally created, and can't be changed by the server owner.
title2A descriptive title for the episode.
viewGroupThe group type used to view the episode.
viewModeUnknown integer value.

Within the MediaContainer there are one or more Video child elements. Each Video element represents one episode available on the Plex server for the season.

Video Attributes
AttributeDescription
ratingKeyA key associated with the episode.
keyThe relative URL of the episode information.
parentRatingKeyThe relative URL of the information for the season.
grandparentRatingKeyThe relative URL of the information for the TV show.
guidThe unique identifier comprised of the Plex agent and episode identifier for the agent.
parentGuidThe GUID for the season.
grandparentGuidThe GUID for the TV show.
typeThe type of media.
titleThe title of the episode.
titleSortThe title of the episode used to sort the episodes in a collection or list.
grandparentKeyThe unique identifier for the TV show.
parentKeyThe unique identifier for the season.
grandparentTitleThe title of the TV show.
parentTitleThe title of the season.
contentRatingThe content rating associated with the episode.
summaryA summary of the episode.
indexThe index of the episode.
parentIndexThe index of the season.
yearThe year the episode was released.
thumbThe thumbnail for the episode.
artThe background artwork used to represent the episode.
parentThumbThe thumbnail for the season.
grandparentThumbThe thumbnail for the TV show.
grandparentArtThe background artwork used to represent the TV show.
grandparentThemeThe theme of the TV show.
durationThe length of the episode in milliseconds.
originallyAvailableAtThe original release date of the episode.
addedAtThe date and time, in Unix time, the episode was added to the library.
updatedAtThe date and time in epoch time, the episode was updated in the library.

Within the Video there are one or more Media child elements. Each Media element represents one media file of the episode 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 episode.
durationThe length of the episode in milliseconds.
bitrateThe bitrate of the episode.
widthThe width of the episode.
heightThe height of the episode.
aspectRatioThe aspect ratio of the episode.
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 episode container.
videoFrameRateThe framerate standard used for the video.
optimizedForStreamingThe media item is optimized for streaming.
0 - not optimized, 1 - optimized.
audioProfileThe audio profile of the media.
has64bitOffsetsThe media item contains 64 bit offsets
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 episode. If the episode has been added to the Plex server as a multi-part episode, 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.
has64bitOffsetsThe media item contains 64 bit offsets
optimizedForStreamingThe media item is optimized for streaming.
0 - not optimized, 1 - optimized.
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 episode.
Director Attributes
AttributeDescription
tagA director of the episode.
Writer Attributes
AttributeDescription
tagA writer for the episode
Country Attributes
AttributeDescription
tagA country of origin for the episode.
Collection Attributes
AttributeDescription
tagThe name of a collection containing the episode.
Role Attributes
AttributeDescription
tagThe name of a person with a role in the episode.

If the include_guids parameter was specified with the value of 1, then there would be a Guid element for each online metadata service associated with the item.

Remarks

To reduce the number of items returned, you can filter the API response to only return items that meet a specific criteria.

For more information, check out the Filter page.

Examples

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