Perform Search

This API command performs a search across all libraries or within a single library. The response is grouped by type.

This command will perform spell checking, looking for partial matches and orders the hubs based on the quality of results.

It will also return related matches, such as returning movies for a genre that is a match for the search query.

URL

GET http://{ip_address}:32400/hubs/search/?X-Plex-Token={plex_token}&query={query_string}&limit={limit}&sectionId={id}

Parameters

Return Status

Response

XML string value that contains all the items in the Plex server that match the search criteria. The items are grouped into hubs. An example of the XML is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="17">
    <Hub title="Movies" type="movie" hubIdentifier="movie" context="" size="3" more="0" style="shelf">
        <Video librarySectionTitle="Movies" score="0.53091" ratingKey="217346" key="/library/metadata/217346" guid="plex://movie/5d776829151a60001f24b3db" studio="Marvel Studios" type="movie" title="Iron Man" titleSort="Iron Man 01" librarySectionID="2" librarySectionKey="/library/sections/2" contentRating="PG-13" summary="After being held captive in an Afghan cave, billionaire engineer Tony Stark creates a unique weaponized suit of armor to fight evil." rating="9.4" audienceRating="9.1" year="2008" tagline="Heroes aren't born. They're built." thumb="/library/metadata/217346/thumb/1683272336" art="/library/metadata/217346/art/1683272336" duration="7561717" originallyAvailableAt="2008-04-30" addedAt="1577944931" updatedAt="1683272336" audienceRatingImage="rottentomatoes://image.rating.upright" chapterSource="media" primaryExtraKey="/library/metadata/283491" ratingImage="rottentomatoes://image.rating.ripe">
            <Media id="276669" duration="7561717" bitrate="9682" width="1920" height="800" aspectRatio="2.35" audioChannels="6" audioCodec="ac3" videoCodec="h264" videoResolution="1080" container="mkv" videoFrameRate="24p" videoProfile="high">
                <Part id="276999" key="/library/parts/276999/1577940796/file.mkv" duration="7561717" file="M:\Media\Movies\Iron Man (2008)\Iron Man (2008) [1080p h.264][AAC AC3 TrueHD].mkv" size="9220910229" container="mkv" videoProfile="high" />
            </Media>
            <Genre tag="Action" />
            <Genre tag="Adventure" />
            <Country tag="United States of America" />
            <Collection tag="Iron Man" />
            <Collection tag="Marvel Universe" />
            <Director tag="Jon Favreau" />
            <Writer tag="Stan Lee" />
            <Writer tag="Jack Kirby" />
            <Role tag="Robert Downey Jr." />
            <Role tag="Terrence Howard" />
            <Role tag="Jeff Bridges" />
        </Video>
      ...
    </Hub>
    <Hub title="Tracks" type="track" hubIdentifier="track" context="" size="3" more="0" style="shelf">
        <Track librarySectionTitle="iTunes" score="0.51000" ratingKey="56064" key="/library/metadata/56064" parentRatingKey="56059" grandparentRatingKey="56058" guid="plex://track/5d07e974403c640290b5e79d" parentGuid="plex://album/5d07c8b5403c640290c202bd" grandparentGuid="plex://artist/5d07bbfc403c6402904a5ed1" parentStudio="Island" type="track" title="Iris (Hold Me Close)" grandparentKey="/library/metadata/56058" parentKey="/library/metadata/56059" librarySectionID="9" librarySectionKey="/library/sections/9" grandparentTitle="U2" parentTitle="Songs of Innocence" summary="" index="5" parentIndex="1" ratingCount="83418" parentYear="2014" thumb="/library/metadata/56059/thumb/1679377162" art="/library/metadata/56058/art/1683272264" parentThumb="/library/metadata/56059/thumb/1679377162" grandparentThumb="/library/metadata/56058/thumb/1683272264" grandparentArt="/library/metadata/56058/art/1683272264" duration="319506" addedAt="1430698153" updatedAt="1681987327">
            <Media id="57782" duration="319506" bitrate="264" audioChannels="2" audioCodec="aac" container="mp4" optimizedForStreaming="1" audioProfile="lc" has64bitOffsets="0">
                <Part id="57885" key="/library/parts/57885/1430698153/file.m4a" duration="319506" file="M:\Media\Music - iTunes\Music\U2\Songs of Innocence\05 Iris (Hold Me Close).m4a" size="11149865" audioProfile="lc" container="mp4" has64bitOffsets="0" hasThumbnail="1" optimizedForStreaming="1" />
            </Media>
        </Track>
        ...
    </Hub>
    <Hub title="Actors" type="actor" hubIdentifier="actor" context="" size="3" more="0" style="shelf">
        <Directory key="/library/sections/2/all?actor=69641" librarySectionID="2" librarySectionKey="/library/sections/2" librarySectionTitle="Movies" librarySectionType="1" reason="section" reasonID="2" reasonTitle="Movies" score="0.52000" type="tag" id="69641" filter="actor=69641" tag="Irrfan Khan" tagType="6" thumb="https://metadata-static.plex.tv/2/people/276d97a28b83ff87efe20150f0c18e2a.jpg" count="3" />
        <Directory key="/library/sections/2/all?actor=68002" librarySectionID="2" librarySectionKey="/library/sections/2" librarySectionTitle="Movies" librarySectionType="1" reason="section" reasonID="2" reasonTitle="Movies" score="0.52000" type="tag" id="68002" filter="actor=68002" tag="Irving Bacon" tagType="6" thumb="https://metadata-static.plex.tv/people/5d7768274de0ee001fcc88ec.jpg" count="2" />
      ...
</MediaContainer>

The XML returned provides a list of the all items on the Plex server that match the search criteria. The root is the MediaContainer element. This element only contains the size attribute that indicates the total number of hubs returned.

Within the MediaContainer there are many ViHubdeo child elements. Each Hub element represents hub group containing items that match the query.

A hub element can contain various child elements. The child elements depends on what the type of item the hub element contains. The next few sections will detail the various information that a hub element can contains.

Within the Hub there can be none or multiple Video child elements. Each Video element represents one video available on the Plex server.

Within the Video there are one or more Media child elements. Each Media element represents one media file of the movie 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 movie. If the movie has been added to the Plex server as a multi-part movie, 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.

For music hubs, there is none or multiple Track child elements that contain the details about the music items in the hub.

The parent item for the tracks refers to the album that includes the track.

Within the Track there are one or more Media child elements. Each Media element represents one media file of the track available on the Plex server.

Within the Media there are one or more Part child elements.

Examples

curl -X GET http://{ip_address}:32400/hubs/search/?X-Plex-Token={plex_token}&query={query_string}&limit={limit}&sectionId={id}

import requests
plex_url = http://{ip_address}:32400/hubs/search/?X-Plex-Token={plex_token}&query={query_string}&limit={limit}&sectionId={id}
response = requests.get(plex_url)
print(response.text)

$response = Invoke-RestMethod 'http://{ip_address}:32400/hubs/search/?X-Plex-Token={plex_token}&query={query_string}&limit={limit}&sectionId={id}' -Method 'GET'
Write-Output $response