# /pcpartpicker/products/search `POST /api/pcpartpicker/products/search` Price: 20 credits Search one PCPartPicker component category — CPUs, coolers, motherboards, memory, storage, video cards, power supplies, cases, case fans, monitors, keyboards, mice, headphones, speakers, webcams, sound and network cards, fan controllers, thermal paste, optical drives, operating systems and UPS units. Narrows by any option filter the category publishes (manufacturer, chipset, socket, memory type, form factor, colour, rating and the rest), by numeric ranges such as price, capacity, clock speed, wattage, length and port counts, and by a keyword matched against product names. Returns each product with its PCPartPicker code, name, image, the category's own spec columns, the current cheapest price and the community star rating. ## How to use it One call covers one `category`; there is no cross-category search here, so resolve a bare product name with /pcpartpicker/products/suggestions first if you do not know which category it belongs to. `filters` and `ranges` are named with the filter-group headings this category shows, and they differ per category — read them from /pcpartpicker/products/filters rather than guessing, because an unknown group or option is rejected with the list of valid ones. Values inside one group are ORed and separate groups are ANDed. Numeric groups other than Price take a unit specific to the group — GB, MHz, W, mm, or a bare count. `region` switches merchants and currency, not the catalogue, so the same product appears in every region with a different price, which is why the Price range is read against whichever `region` was requested. Note that `price` here is PCPartPicker's cached listing figure and can disagree with the live merchant offers; the Price range filter and /pcpartpicker/products get their number from the merchant table. Each card's `specs` entry here is {name, value: str} — one value per spec name; /pcpartpicker/products carries its own, differently-shaped `specs` ({name, values: list[str]}), since some specs there are multi-valued. ## Parameters - `access-token` (string, required) ## Request body - `timeout` (integer) — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500) - `category` (string, required) — Component category to search (one of: "cpu", "cpu-cooler", "motherboard", "memory", "internal-hard-drive", "video-card", "power-supply", "case", "headphones", "keyboard", "mouse", "speakers", "webcam", "monitor", "os", "sound-card", "wired-network-card", "wireless-network-card", "case-fan", "fan-controller", "thermal-paste", "external-hard-drive", "optical-drive", "ups") - `region` (string) — PCPartPicker country site, which decides the merchants and the currency of every price (default: "us"; one of: "au", "at", "be", "ca", "cz", "dk", "fi", "fr", "de", "hu", "ie", "it", "nl", "nz", "no", "pl", "pt", "ro", "sa", "sk", "es", "se", "uk", "us") - `search` (string, nullable) — Keyword matched against product names inside the chosen category (examples: "astral", "9800x3d"; minLength: 1) - `filters` (array, nullable) — Option filters, each naming a filter group of this category and the option labels to accept. Groups and labels are category-specific and are rejected with the list of what this category publishes - `name` (string, required) — Filter group name exactly as the category publishes it (examples: "Manufacturer", "Memory Type", "Chipset"; minLength: 1) - `values` (array, required) — Option labels to accept; several labels widen the group, several groups intersect (examples: ["Asus","MSI"]; minItems: 1) - `ranges` (array, nullable) — Numeric filters, each naming a numeric group of this category with a lower and/or upper bound in that group's own unit. Price is the group named Price and takes whole currency units - `name` (string, required) — Numeric filter group name exactly as the category publishes it (examples: "Price", "Memory", "Boost Clock"; minLength: 1) - `minimum` (number, nullable) — Lower bound in the group's own unit; omitted means the group's published minimum - `maximum` (number, nullable) — Upper bound in the group's own unit; omitted means the group's published maximum - `sort` (string, nullable) — Ordering, given as the value or the label this category publishes; a leading minus reverses it. Rejected with the list of what this category offers (examples: "price", "-rating", "Name (Ascending)"; minLength: 1) - `count` (integer, required) — Max number of results to return (min: 1; max: 20000) ## Response ### 200 — Successful Response - `@type` (string) (default: "PcpartpickerProductCard") - `id` (string, required) - `internal_id` (string, nullable) - `url` (string, nullable) - `name` (string, nullable) - `image` (string, nullable) - `price` (number, nullable) - `rating` (number, nullable) - `review_count` (integer, nullable) - `specs` (array) (default: []) - `@type` (string) (default: "PcpartpickerSpec") - `name` (string, required) - `value` (string, required) ## Errors ### 422 — Validation Error A filter group, an option label or a sort value that this category does not publish What to do: Check the fields against this schema. A URN with the wrong prefix is the most common cause. - `detail` (array) - `loc` (array, required) - `msg` (string, required) - `type` (string, required) - `input` (any) - `ctx` (object) ### 408 The request ran past its time limit What to do: Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner. ### 412 The category page did not come back with a product table What to do: Retrying will not help: either the entity does not exist, or the input points at a different one. ### 429 Too many requests: a rate limit or a usage window is exhausted What to do: When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit. ### 500 Something broke on our side What to do: Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers. ### 529 Rate limit reached, or the endpoint is overloaded What to do: Wait at least 30 seconds, then retry. ## Response envelope Success: Array of objects (may be empty if no results) Error: Error may coexist with partial results if it occurs mid-execution. Check X-Error header and status code. Every response carries these headers: - `X-Error` — Error message text (present only on error) - `X-Request-ID` — Unique request identifier - `X-Execution-Time` — Execution time in seconds - `X-Result-Count` — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently. - `X-Total-Available-Results` — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact. - `X-Warning` — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry. - `X-Retry-After` — Seconds to wait before retrying. Present only on 429.