Filtering
When running the Plex API commands to return a list of media items, it may be helpful to filter the list of items to only a select few. This is more helpful if you have thousands of media items in your Plex library.
The API provides the ability to filter out items that are of interest to you. A filter can be applied to any attribute that is returned in the response from the Plex server.
How to use filtering with the Plex API
Filters are expressed using a querystring parameter. Each querystring contains a field, an operator, and a value. For example, to specify a filter, you would use:
http://{ip_address}:32400/library/sections/{id}/all?X-Plex-Token={plex_token}&{field}{operator}{value}A field is any valid attribute that is returned in a response from the Plex server. For example, the year attribute for a movie or the contentRating attribute for a TV show.
The field name is case-sensitive, so you will need to use contentRating and not contentrating. The API will return a 200 (success) status code, but the response will include all media items for the library, instead of just the filtered items.
The operator is used to compare the attribute values with the value provided in the querystring. The following table lists the valid operators:
| Operator | Description |
|---|---|
| = | Returns all media that is tagged with or equal to the value. |
| != | Returns all media that is not tagged with or not equal to the value. |
| >= | Returns all media that is greater than or equal to the value. |
| <= | Returns all media that is less than or equal to the value. |
Examples of using the operators with both string and numeric values are given below.
The value is used to compare with the actual value of the field. The value provided in the querystring may or may not be case-sensitive. For example, when filtering by studio, "marvel" and "Marvel" will return the same media items, but when filtering by content rating, that value is case-sensitive.
You can specify multiple filter parameters for a request. When you do specify multiple filters, they will be logically ANDed together, which means only media items that satisfy all the filter criteria will be returned.
Filtering examples
The following are filtering examples that can be used with the Plex API. Note: the movies library ID is 2, while the TV shows library is 3 in the examples.
Example 1
Get a list of all Marvel movies in a library:
GET http://192.168.1.4:32400/library/sections/2/all?X-Plex-Token=L6vkd7JtLHjsH5987vYY&studio=marvel
Note, the actual studio name is "Marvel Studios", but only part of a string needs to match for an item to be returned.
Example 2
Get a list of all Marvel movies in a library that were released from the year 2011 and later:
GET http://192.168.1.4:32400/library/sections/2/all?X-Plex-Token=L6vkd7JtLHjsH5987vYY&studio=marvel&year>=2011
Example 3
Get a list of all TV shows that have a TV-Y content rating:
GET http://192.168.1.4:32400/library/sections/3/all?X-Plex-Token=L6vkd7JtLHjsH5987vYY&contentRating=TV-Y
The contentRating field is a string value, it has specific values it uses, and is case-sensitive.
Example 4
If you use a specific naming convention for your movies that includes the codecs used for the video and audio streams in the file names, you can filter on values in the file names. The following will return all moves that have AC3 in the file name:
GET http://192.168.1.4:32400/library/sections/2/all?X-Plex-Token=L6vkd7JtLHjsH5987vYY&file=ac3