Search Amazon products
1. Function
Discover candidate Amazon products by keyword, category and business metrics, returning a paginated list of the shared Product model (max 100 per page). Reads the catalog snapshot: omit dateRange or pass 'Nd' for the latest daily snapshot, or 'YYYY-MM' for that month's month-end snapshot (earliest 2026-02). Filters include price, monthly sales and revenue floors, growth rates, BSR and its 7-day change, rating, seller count, brand and seller lists, badges, fulfillment, package weight in ounces, package size tier, Buy Box seller country, gross margin rate and category scope. Setting any range or list filter excludes products whose value is unknown, so a narrower result set is a coverage effect, not a market finding. categoryScope=includeChildren (default) matches the given category levels and every subcategory; exactOnly requires the product's path to end at the last given level. monthlySalesFloor is the page's 'N+ bought in past month' figure carried forward by the catalog snapshot, a lower bound rather than an estimate. Billing: 1 credit per request.
2. Use cases
Use search to find products you do not know yet — niche discovery, competitor screening, filtering by margin or growth. Use /products/detail to read ASINs or a parent's variants you already know; it takes no filters. Use /products/competitors for competitor lookup around one ASIN, and /markets/search for category-level demand and competition.
### Responses:
**200**: Successful Response (Success Response)
Content-Type: application/json
**Example Response:**
```json
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}
```
**Output Schema:**
```json
{
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"description": "Whether the request was successful",
"default": true
},
"data": {
"title": "Data",
"description": "Response data payload"
},
"error": {
"description": "Error details if request failed"
},
"meta": {
"description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
"properties": {
"requestId": {
"type": "string",
"title": "Requestid",
"description": "Unique request identifier"
},
"timestamp": {
"type": "string",
"title": "Timestamp",
"description": "Response timestamp in ISO 8601 format"
},
"total": {
"title": "Total",
"description": "Total number of records"
},
"page": {
"title": "Page",
"description": "Current page number"
},
"pageSize": {
"title": "Pagesize",
"description": "Number of records per page"
},
"totalPages": {
"title": "Totalpages",
"description": "Total number of pages"
},
"creditsRemaining": {
"title": "Creditsremaining",
"description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
},
"creditsConsumed": {
"title": "Creditsconsumed",
"description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
},
"creditsRemainingExact": {
"title": "Creditsremainingexact",
"description": "Remaining API credits, precise to 1 decimal place"
},
"creditsConsumedExact": {
"title": "Creditsconsumedexact",
"description": "Credits consumed by this request, precise to 1 decimal place"
},
"tokensUsage": {
"description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
}
},
"type": "object",
"required": [
"requestId",
"timestamp"
],
"title": "ResponseMeta"
}
},
"type": "object",
"required": [
"meta"
],
"title": "OpenApiResponse[list[Product]]",
"examples": []
}
```
**422**: Validation Error
Content-Type: application/json
**Example Response:**
```json
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}
```
**Output Schema:**
```json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
```
