Get All TV Show Seasons

Each TV show added to a Plex server can have one or more seasons associated with it. You can use this API command to get information about each season.

URL

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

Parameters

NameDescription
ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex token.
idThe key associated with a TV show. This key can be found by calling the Get all TVShows command and using the value in the ratingKey attribute.
include_guids(Optional) Returns the GUID values of the online metadata services associated to the media item.

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 seasons in the library. An example of the XML returned from the request is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="5" allowSync="1" art="/library/metadata/275479/art/1673348103" identifier="com.plexapp.plugins.library" key="275479" 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" parentYear="1983" sortAsc="1" summary="In this half-hour program, artist Bob Ross paints a beautiful oil painting on canvas." theme="/library/metadata/275479/theme/1673348103" thumb="/library/metadata/275479/thumb/1673348103" title1="TV Shows" title2="The Joy of Painting" viewGroup="season" viewMode="458810">
    <Directory leafCount="52" thumb="/library/metadata/275479/thumb/1673348103" viewedLeafCount="0" key="/library/metadata/275479/allLeaves" title="All episodes" />
    <Directory ratingKey="275480" key="/library/metadata/275480/children" parentRatingKey="275479" guid="plex://season/602e683d88e0a9002df8a4ff" parentGuid="plex://show/5d9c086e3c3f87001f34fc00" parentStudio="WIPB" type="season" title="The Joy of Painting" titleSort="Joy of Painting" parentKey="/library/metadata/275479" parentTitle="The Joy of Painting" 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." index="1" parentIndex="1" parentYear="1983" thumb="/library/metadata/275480/thumb/1659190872" art="/library/metadata/275479/art/1673348103" parentThumb="/library/metadata/275479/thumb/1673348103" parentTheme="/library/metadata/275479/theme/1673348103" leafCount="13" viewedLeafCount="0" addedAt="1619710207" updatedAt="1659190872"></Directory>
    <Directory ratingKey="275494" key="/library/metadata/275494/children" parentRatingKey="275479" guid="plex://season/602e683e88e0a9002df8a504" parentGuid="plex://show/5d9c086e3c3f87001f34fc00" parentStudio="WIPB" type="season" title="Season 2" parentKey="/library/metadata/275479" parentTitle="The Joy of Painting" summary="Season 2 of The Joy of Painting with Bob Ross features the following wonderful painting instructions: Meadow Lake, Winter Sun, Ebony Sea, Shades of Grey, Autumn Splendor, Black River, Brown Mountain, Reflections, Black and White Seascape, Lazy River, Black Waterfall, Mountain Waterfall, Final Grace." index="2" parentIndex="1" parentYear="1983" thumb="/library/metadata/275494/thumb/1659190874" art="/library/metadata/275479/art/1673348103" parentThumb="/library/metadata/275479/thumb/1673348103" parentTheme="/library/metadata/275479/theme/1673348103" leafCount="13" viewedLeafCount="0" addedAt="1619733355" updatedAt="1659190874"></Directory>
    ...
</MediaContainer>

The XML returned provides a list of the all seasons for a TV show 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 TV show seasons on the server.

MediaContainer Attributes
AttributeDescription
sizeThe number of TV show seasons.
allowSync1 - allow syncing content.
0 - don't allow syncing content.
artBackground artwork used to represent the TV show season.
identifierThe type of item.
keyUnique identifier for the TV show season.
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 TV show.
parentTitleThe title of the TV show.
parentYearThe year of the TV show.
sortAsc1 - the library is sorted in ascending order.
0 - the library is sorted in descending order.
summaryThe summary for the TV show season.
themeThe theme for the TV show season.
thumbThe thumbnail for the TV show season.
title1The title of the TV show season.
Note: This appears to be internally created, and can't be changed by the server owner.
title2A descriptive title for the TV show season.
viewGroupThe group type used to view the TV show season.
viewModeUnknown integer value.

Within the MediaContainer there are one or more Directory child elements. The first Directory element is used to view all episodes for the TV show.

Directory Attributes
AttributeDescription
leafCountThe number of items in the TV show season.
thumbThe thumbnail for the TV show season.
viewedLeafCountThe number of the TV show season items that have been viewed.
keyThe relative URL of the information for the TV show season.
titleThe name of the TV show season.

After the 'All Episodes' Directory element, there is a Directory element for each season for the TV show that is available on the Plex server.

Directory Attributes
AttributeDescription
ratingKeyA key associated with the TV show season.
keyThe relative URL of the information for the TV show season.
parentRatingKeyA key associated with the TV show.
guidThe unique identifier for the TV show season.
parentGuidThe unique identifier associated with the TV show.
parentStudioThe studio associated with the TV show.
typeThe type of item represented by this Directory element.
titleThe name of the TV show season.
titleSortThe title used to sort the seasons.
parentKeyThe key associated with the TV show.
parentTitleThe title associated with the TV show.
summaryInformation about the TV show season.
indexUnknown.
parentIndexThe index associated with the TV show.
parentYearThe studio associated with the TV show.
thumbThe thumbnail for the TV show season.
artThe background artwork used to represent the TV show season.
parentThumbThe studio associated with the TV show.
parentThemeThe theme song associated with the TV show.
leafCountThe number of items in the TV show season.
viewedLeafCountThe number of the TV show season items that have been viewed.
addedAtThe date and time the TV show season was added to the library.
updatedAtThe date and time the TV show season was updated in the library.

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.

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