Skip to main content
POST
Shopping search

Authorizations

x-api-key
string
header
required

Body

application/json

Shopping search request: products to buy, each linked to a store's page.

search_queries
string[]
required

Keyword product queries, such as a model name or a product type with its attributes. At least one query is required, and at most 5, each at most 200 characters.

Maximum array length: 5
Maximum string length: 200
Examples:
objective
string | null

Natural-language description of the products wanted, used with search_queries to focus results. At most 5000 characters.

min_price
number | null

Only products priced at least this, in the market's currency. Products without a known price are left out.

Required range: x >= 0
max_price
number | null

Only products priced at most this, in the market's currency. Products without a known price are left out.

Required range: x > 0
condition
default:new

new (default), used, refurbished or any. Leaves out products known to be in another condition; most stores do not state one, so for used or refurbished also say it in the queries.

Available options:
new,
used,
refurbished
mode
enum<string> | null

advanced (default): live store listings from many sources.

Available options:
advanced
session_id
string | null

Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.

Maximum string length: 1000
client_model
string | null

The model generating this request and consuming the results.

Example:

"claude-opus-4-7"

advanced_settings
AdvancedProductSearchSettings · object | null

Advanced configuration for market and result count.

Response

Successful Response

Shopping search response.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_id
string
required

Session identifier, echoed back from the request when nonempty; otherwise generated by the server. Pass it to later calls made as part of the same task.

Example:

"session_8a911eb27c7a4afaa20d0d9dc98d07c0"

results
ProductSearchResult · object[]
required

Products by decreasing relevance, in three groups: distinct products, then one seller's other options of an earlier product, then products that are out of stock.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.