---
title: "Search Amazon products by keyword"
method: GET
path: "/search"
tags: ["Amazon Data"]
---

# Search Amazon products by keyword

`GET /search`

## Request

- Base URL: `https://dash.apiguru.app/api/v1`
- URL: `https://dash.apiguru.app/api/v1/search`
- Auth: one of:
  - API key in header `X-API-KEY`
  - API key in query parameter `api_key`
  - none

Use to find products by keyword and filters. Rows are result snippets; for the authoritative record of one ASIN call product_details. Search Amazon products by keyword. Filters: page, sort_by, category_id (browse node), min_price / max_price (decimals), product_condition (NEW / USED / RENEWED), brand, seller_id, today_deals and deal_type (coupons, all_discounts, buy_more_save_more). Every answer carries filters_applied, filters_ignored (with the reason) and available_filters for that marketplace.

**Price:** $0.003 per call

**Notes:** Blank values and the literal string 'null' are treated as unset. Invalid page, sort_by, price, product_condition or deal_type is a free 400 naming the parameter and the allowed values. Condition and deal refinements are per marketplace; a marketplace that lacks one gets the unfiltered feed plus an entry under filters_ignored, never a silent empty page. `product_num_ratings` is an integer; `offers_count` is the "N offers" count a result card shows, an integer, and null when the card shows none (most cards; it used to default to 1); `product_brand` is the brand line Amazon prints above some titles (fashion and many branded listings) and null on cards without one -- product_details has `brand_name` for every ASIN; `product_star_rating`, `product_price` and `product_original_price` are decimal strings; a null field means Amazon did not show it. `is_prime` is true when the result carries a Prime badge or its delivery line offers Prime delivery. `metadata.reachable_pages` says how far `page` can go: Amazon serves at most 7 pages of a query even when `metadata.total_pages` counts more (then `pagination_note` says how to split the query). `_links.next` is the next page while there is one; a page past the end is a free 400 `page_out_of_range`. A full page is up to 48 results and about 54 KB; the tool returns the first 10 as light rows by default and the answer carries `_truncated`, `_omitted_fields`, `_projection` and `_notes`. filters_applied echoes the effective sort_by (RELEVANCE when none was sent). A BEST_SELLERS ordering is Amazon's query-scoped popularity, not a category rank: a row's `badges` / `is_best_seller` are what the result card showed for this query, and an ASIN that is #1 in its subcategory can carry no badge here while product_details reports best_seller=true with the rank. For a rank claim, use product_details or best_sellers. An empty `products` list is served as success only when Amazon itself reports 0 results (metadata.total is 0 and `hint` says so). Anything else that is not a usable result is an unbilled, retryable 503 with code upstream_unavailable.

## Query parameters

- `query` string, required
- `page` integer
- `geo` 'US' | 'CA' | 'DE' | 'MX' | 'UK' | 'FR' | 'IT' | 'ES' | 'AU' | 'BR' | 'IN' | 'JP' | 'NL' | 'AE' | 'PL' | 'SA' | 'SG' | 'SE' | 'TR' | 'BE' | 'IE' | 'ZA' | 'EG'
- `sort_by` 'RELEVANCE' | 'BEST_SELLERS' | 'LOW_HIGH_PRICE' | 'HIGH_LOW_PRICE' | 'REVIEWS' | 'NEWEST'
- `category_id` string
- `min_price` number
- `max_price` number
- `product_condition` 'NEW' | 'USED' | 'RENEWED'
- `brand` string
- `seller_id` string
- `today_deals` boolean
- `deal_type` 'today_deals' | 'all_discounts' | 'coupons' | 'buy_more_save_more'

## Response `200`

Success.

- object

## Other responses

- `400`: Bad input (bad ASIN format, unknown geo, missing required param), or a page past the last one Amazon serves for a list (`code: page_out_of_range`, with `reachable_pages`). On agent.apiguru.app an `api_key` in the URL is refused the same way (`code: api_key_in_query`): send it as the X-API-KEY header. NOT billed.
- `401`: Missing or invalid API key on the keyed path.
- `402`: Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge (over MCP: an x402 PaymentRequired tool result, payable in-band via _meta["x402/payment"]). On the keyed path it means the account balance is exhausted.
- `403`: Account disabled, or no active subscription plan.
- `404`: The ASIN genuinely does not exist on that marketplace. BILLED - the lookup was performed and the bad input was the caller's. Retrying will not help; try a different geo.
- `413`: Too many items in a batch request.
- `429`: Per-second rate limit exceeded for the plan (`code: rate_limited`, `Retry-After: 1`). NOT billed. Back off and retry.
- `500`: Internal error. NOT billed.
- `502`: Bad gateway. NOT billed. Same class as 503: retry with backoff.
- `503`: Temporary failure on our side (`code: upstream_unavailable`). NOT billed. Safe and correct to retry.
- `504`: Gateway timeout: no answer within 55 s, so agent.apiguru.app stopped the request before it was billed (`code: deadline_exceeded`). NOT billed. Retry once; a batch with fewer items answers sooner.
- `timeout`: No response before your own client's deadline. A keyless call without a payment is never billed. On an API key, or with an x402 payment attached, the request may still complete after your client gave up, and is then billed like any answered call. Some marketplaces answer more slowly than others; allow 60s rather than retrying early (agent.apiguru.app answers a 504 itself at 55 s).

---

[API](https://skmtc.dev/apiguru/apis/apiguru-amazon-data-api.md) · [All operations](https://skmtc.dev/apiguru/apis/apiguru-amazon-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/apiguru/apis/apiguru-amazon-data-api/revisions/121618530d03?raw)