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

Return Status

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.

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.

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.

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.

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.

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