Skip to main content
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 .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.
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.

Request Fields

Send requests to POST 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, merchant and brand: 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.
  • price and currency: the price at the store when the API retrieved it, with its ISO 4217 currency code. original_price is set when the product is on sale.
  • rating and review_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, used or refurbished, when known.
  • availability: in_stock, out_of_stock or preorder, when known.
  • offers: other stores’ pages for the same product, each with its own url, merchant, price and currency, when known.
Results are ordered by decreasing relevance. The API omits a field it does not know.

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_price and max_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 condition for used or refurbished products. Results are new by default. Most stores do not state a condition, so products without one are kept. For used or refurbished, also say it in the query, such as "used Sony WH-1000XM5".
  • Set advanced_settings.location to 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 price and availability as the values at search time, and send the shopper to url to confirm them.