For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
Send the Shopping API one or more keyword queries for the products you want. The API
returns products to buy, each linked to a store’s product page, with its price in the
market’s currency.
.md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead.Request Fields
Send requests toPOST https://api.parallel.ai/v1/shopping/search with your API key in the
x-api-key header. search_queries is required; all other fields are optional. The API
rejects unknown fields with a 422.
Example
Response
Each result is one product at one store:url: the store’s product page, where the product can be bought. Never a search page or a price-comparison page.title,merchantandbrand: the product’s name, the store’s name, and the brand when known.description: what the product is and its main specifications, when one is available.priceandcurrency: the price at the store when the API retrieved it, with its ISO 4217 currency code.original_priceis set when the product is on sale.ratingandreview_count: the average rating out of 5 and the number of reviews behind it.image_url: a product image, when one is available.condition:new,usedorrefurbished, when known.availability:in_stock,out_of_stockorpreorder, when known.offers: other stores’ pages for the same product, each with its ownurl,merchant,priceandcurrency, when known.
Markets
advanced_settings.location sets the stores searched and the currency of price, min_price and max_price.
The API serves these markets:
us, ca, mx, br, ar, cl, co, gb, ie, de, at, fr, be, nl, es,
pt, it, fi, gr, ch, se, no, dk, pl, cz, hu, ro, tr, il, ae,
sa, za, in, jp, kr, cn, tw, hk, sg, my, th, id, ph, vn, au
and nz.
For any other valid country code, the API searches the us market and returns a warning.
The API ignores an invalid code, also with a warning.
Searching Well
- Write queries the way a shopper types them. A model name finds that product
(
"Samsung 990 Pro 2TB"). A product type with its key attributes finds a category ("waterproof hiking boots women"). Leave out words such as “buy”, “best” or “cheap”. - Put one product in each query. To compare products, or to cover other names for one product, send several queries in one request, up to five.
- Put the shopper’s intent in
objective. Describe the use, the must-haves and what to avoid, such as"for a small apartment, quiet, no accessories". The API ranks results against it. - Filter on price with
min_priceandmax_price, not in the query. Words such as “under $50” in a query do not filter results. The price filters do, and every result you get back meets them. Products without a known price are left out when you set either one. - Set
conditionfor used or refurbished products. Results are new by default. Most stores do not state a condition, so products without one are kept. Forusedorrefurbished, also say it in the query, such as"used Sony WH-1000XM5". - Set
advanced_settings.locationto the shopper’s country. It changes the stores and the currency. Write queries in that market’s language for the best results. - Check the store’s page before buying. Prices and stock change often. Treat
priceandavailabilityas the values at search time, and send the shopper tourlto confirm them.