---
id: perform-search
sidebar_label: Perform a search
hide_title: true
hide_table_of_contents: true
api: {"tags":["Search"],"operationId":"performSearch","description":"This endpoint performs a search across all library sections, or a single section, and returns matches as hubs, split up by type. It performs spell checking, looks for partial matches, and orders the hubs based on quality of results. In addition, based on matches, it will return other related matches (e.g. for a genre match, it may return movies in that genre, or for an actor match, movies with that actor).\n\nIn the response's items, the following extra attributes are returned to further describe or disambiguate the result:\n\n- `reason`: The reason for the result, if not because of a direct search term match; can be either:\n  - `section`: There are multiple identical results from different sections.\n  - `originalTitle`: There was a search term match from the original title field (sometimes those can be very different or in a foreign language).\n  - `<hub identifier>`: If the reason for the result is due to a result in another hub, the source hub identifier is returned. For example, if the search is for \"dylan\" then Bob Dylan may be returned as an artist result, an a few of his albums returned as album results with a reason code of `artist` (the identifier of that particular hub). Or if the search is for \"arnold\", there might be movie results returned with a reason of `actor`\n- `reasonTitle`: The string associated with the reason code. For a section reason, it'll be the section name; For a hub identifier, it'll be a string associated with the match (e.g. `Arnold Schwarzenegger` for movies which were returned because the search was for \"arnold\").\n- `reasonID`: The ID of the item associated with the reason for the result. This might be a section ID, a tag ID, an artist ID, or a show ID.\n\nThis request is intended to be very fast, and called as the user types.\n","parameters":[{"name":"query","description":"The query term","in":"query","schema":{"type":"string","example":["arnold","dylan"]},"required":true},{"name":"sectionId","description":"This gives context to the search, and can result in re-ordering of search result hubs","in":"query","schema":{"type":"number"},"required":false},{"name":"limit","description":"The number of items to return per hub","in":"query","schema":{"type":"number","example":5,"default":3}}],"responses":{"200":{"description":"The search results"},"401":{"description":"Unauthorized - Returned if the X-Plex-Token is missing from the header or query.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"number","example":1001},"message":{"type":"string","example":"User could not be authenticated"},"status":{"type":"number","example":401}}}}}}}}}},"method":"get","path":"/hubs/search","servers":[{"url":"http://{Local IP}:{Port}","variables":{"Local IP":{"default":"10.10.10.47","description":"The Local IP Address of your plex server"},"Port":{"default":"32400","description":"The port to access your plex server"}}},{"url":"https://{Local IP}:{Port}","variables":{"Local IP":{"default":"10.10.10.47","description":"The Local IP Address of your plex server"},"Port":{"default":"32400","description":"The port to access your plex server"}}}],"security":[{"Token":[],"ClientIdentifier":[],"Device":[],"DeviceName":[],"Platform":[],"PlatformVersion":[],"Product":[],"Version":[]}],"securitySchemes":{"Token":{"description":"Plex Authentication Token","type":"apiKey","in":"header","name":"X-Plex-Token"},"ClientIdentifier":{"description":"Plex Authentication Token","type":"apiKey","in":"header","name":"X-Plex-Client-Identifier"},"DeviceName":{"description":"Primary name for the device eg. `Plex Web (Chrome)`","type":"apiKey","in":"header","name":"X-Plex-Device-Name"},"Device":{"description":"The type of device your application is running on\nDevice name and or model number, eg `iPhone3,2`, `Motorola XOOM™`, `LG5200TV`\n","type":"apiKey","in":"header","name":"X-Plex-Device"},"PlatformVersion":{"description":"Operating system version\neg `4.3.1`, `10.6.7`, `3.2`\n","type":"apiKey","in":"header","name":"X-Plex-Platform-Version"},"Platform":{"description":"Platform name \neg: `Web`, `iOS`, `MacOSX`, `Android`, `LG`\n","type":"apiKey","in":"header","name":"X-Plex-Platform"},"Product":{"description":"Plex application name \neg: `Laika`, `Plex Media Server`, `Media Link`\n","type":"apiKey","in":"header","name":"X-Plex-Product"},"Version":{"description":"Plex application version number","type":"apiKey","in":"header","name":"X-Plex-Version"}},"info":{"title":"Plex-API","summary":"A Plex Media Server API Map","description":"An Open API Spec for interacting with Plex.tv and Plex Servers","version":"0.0.3","contact":{"name":"Luke Hagar","url":"https://www.LukeHagar.com","email":"Lukeslakemail@gmail.com"},"license":{"name":"MIT","identifier":"MIT","url":"https://opensource.org/licenses/MIT"}},"postman":{"name":"Perform a search","description":{"content":"This endpoint performs a search across all library sections, or a single section, and returns matches as hubs, split up by type. It performs spell checking, looks for partial matches, and orders the hubs based on quality of results. In addition, based on matches, it will return other related matches (e.g. for a genre match, it may return movies in that genre, or for an actor match, movies with that actor).\n\nIn the response's items, the following extra attributes are returned to further describe or disambiguate the result:\n\n- `reason`: The reason for the result, if not because of a direct search term match; can be either:\n  - `section`: There are multiple identical results from different sections.\n  - `originalTitle`: There was a search term match from the original title field (sometimes those can be very different or in a foreign language).\n  - `<hub identifier>`: If the reason for the result is due to a result in another hub, the source hub identifier is returned. For example, if the search is for \"dylan\" then Bob Dylan may be returned as an artist result, an a few of his albums returned as album results with a reason code of `artist` (the identifier of that particular hub). Or if the search is for \"arnold\", there might be movie results returned with a reason of `actor`\n- `reasonTitle`: The string associated with the reason code. For a section reason, it'll be the section name; For a hub identifier, it'll be a string associated with the match (e.g. `Arnold Schwarzenegger` for movies which were returned because the search was for \"arnold\").\n- `reasonID`: The ID of the item associated with the reason for the result. This might be a section ID, a tag ID, an artist ID, or a show ID.\n\nThis request is intended to be very fast, and called as the user types.\n","type":"text/plain"},"url":{"path":["hubs","search"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The query term","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"This gives context to the search, and can result in re-ordering of search result hubs","type":"text/plain"},"key":"sectionId","value":""},{"disabled":false,"description":{"content":"The number of items to return per hub","type":"text/plain"},"key":"limit","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}}
sidebar_class_name: "get api-method"
info_path: docs/plex-media-server/plex-api
---

import ApiTabs from "@theme/ApiTabs";
import DiscriminatorTabs from "@theme/DiscriminatorTabs";
import MethodEndpoint from "@theme/ApiDemoPanel/MethodEndpoint";
import MimeTabs from "@theme/MimeTabs";
import ParamsItem from "@theme/ParamsItem";
import ResponseSamples from "@theme/ResponseSamples";
import SchemaItem from "@theme/SchemaItem";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";

<h1 className={"openapi__heading"}>Perform a search</h1>

<MethodEndpoint method={"get"} path={"/hubs/search"}></MethodEndpoint>



This endpoint performs a search across all library sections, or a single section, and returns matches as hubs, split up by type. It performs spell checking, looks for partial matches, and orders the hubs based on quality of results. In addition, based on matches, it will return other related matches (e.g. for a genre match, it may return movies in that genre, or for an actor match, movies with that actor).

In the response's items, the following extra attributes are returned to further describe or disambiguate the result:

- `reason`: The reason for the result, if not because of a direct search term match; can be either:
  - `section`: There are multiple identical results from different sections.
  - `originalTitle`: There was a search term match from the original title field (sometimes those can be very different or in a foreign language).
  - `<hub identifier>`: If the reason for the result is due to a result in another hub, the source hub identifier is returned. For example, if the search is for "dylan" then Bob Dylan may be returned as an artist result, an a few of his albums returned as album results with a reason code of `artist` (the identifier of that particular hub). Or if the search is for "arnold", there might be movie results returned with a reason of `actor`
- `reasonTitle`: The string associated with the reason code. For a section reason, it'll be the section name; For a hub identifier, it'll be a string associated with the match (e.g. `Arnold Schwarzenegger` for movies which were returned because the search was for "arnold").
- `reasonID`: The ID of the item associated with the reason for the result. This might be a section ID, a tag ID, an artist ID, or a show ID.

This request is intended to be very fast, and called as the user types.


<details style={{"marginBottom":"1rem"}} className={"openapi-markdown__details"} data-collapsed={false} open={true}><summary style={{}}><strong>Query Parameters</strong></summary><div><ul><ParamsItem className={"paramsItem"} param={{"name":"query","description":"The query term","in":"query","schema":{"type":"string","example":["arnold","dylan"]},"required":true}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"sectionId","description":"This gives context to the search, and can result in re-ordering of search result hubs","in":"query","schema":{"type":"number"},"required":false}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"limit","description":"The number of items to return per hub","in":"query","schema":{"type":"number","example":5,"default":3}}}></ParamsItem></ul></div></details><div><div><ApiTabs><TabItem label={"200"} value={"200"}><div>

The search results

</div><div></div></TabItem><TabItem label={"401"} value={"401"}><div>

Unauthorized - Returned if the X-Plex-Token is missing from the header or query.

</div><div><MimeTabs className={"openapi-tabs__mime"} schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs className={"openapi-tabs__schema"}><TabItem label={"Schema"} value={"Schema"}><details style={{}} className={"openapi-markdown__details"} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}} className={"openapi-markdown__details"}><summary style={{}}><strong>errors</strong><span style={{"opacity":"0.6"}}> object[]</span></summary><div style={{"marginLeft":"1rem"}}><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem","paddingBottom":".5rem"}}>Array [</div></li><SchemaItem collapsible={false} name={"code"} required={false} schemaName={"number"} qualifierMessage={undefined} schema={{"type":"number","example":1001}}></SchemaItem><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"User could not be authenticated"}}></SchemaItem><SchemaItem collapsible={false} name={"status"} required={false} schemaName={"number"} qualifierMessage={undefined} schema={{"type":"number","example":401}}></SchemaItem><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem"}}>]</div></li></div></details></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"errors\": [\n    {\n      \"code\": 1001,\n      \"message\": \"User could not be authenticated\",\n      \"status\": 401\n    }\n  ]\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div></div>