List media
list_mediaList and filter movies, shows, episodes, artists, albums, tracks, or collections by watched state, rating, genre, year, and more, returning view counts and last-viewed data.
Instructions
List items from any library with rich filtering. Returns watched state, view counts and last-viewed on every record. watched defaults to 'all': the full library, seen and unseen. For SHOW libraries: the watched filter means any-episode-played (watched) / has-unplayed-episodes (unwatched), while each record's watched field means fully watched. A partially-watched show matches both filters' opposites. kind defaults to the kind a named collection holds, else the library's natural top-level type (movie/show/artist). Use episode/track/album/season for deeper types, or collection to list a section's collections. rated filters on the owner's star rating (userRating, 1-10 internal scale). Movie records carry userRating, and sort=userRating asc puts unrated first. Filters combine (AND). Paginate with offset/limit. detail=true caps limit at 25 and adds fields such as directors, actors, collections and summaries. The result's filters object names what each genre/collection/country/studio/label filter matched: the same name ignoring case first, else the first one containing it. kind=collection lists a section's collections only. Other filters/sort are ignored for collections.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_media"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| sort | No | addedAt | |
| user | No | see the library as this Plex Home user (name or id) | |
| year | No | ||
| genre | No | ||
| label | No | filter to items carrying this Plex label. Plex lists every label on the server under every library, so a label used only in another library returns no items rather than an error | |
| limit | No | ||
| order | No | desc | |
| rated | No | all | |
| decade | No | e.g. '1970s' | |
| detail | No | ||
| fields | No | project each record to these keys (ratingKey always kept). Use to keep large listings small | |
| offset | No | ||
| studio | No | ||
| country | No | ||
| library | No | Movies | |
| watched | No | all | |
| addedSince | No | ISO date or relative like '-30d' | |
| collection | No | filter to members of a collection. Leaving kind out uses the kind of item the collection holds. A smart collection with no tag is an error naming the ratingKey to pass to get_children | |
| contentRating | No | e.g. 'PG-13' | |
| maxDurationMin | No | ||
| lastViewedAfter | No | last viewed after this ISO date or relative like '-30d' | |
| lastViewedBefore | No | last viewed before this ISO date or relative like '-3y'. Never-watched items match too unless watched='watched' |