openapi_v2_products_search
Search Amazon products
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.
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:
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}Output Schema:
{
"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:
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}Output Schema:
{
"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"
}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| badges | No | Include products with these badges. Example: ['bestSeller', 'amazonChoice', 'newRelease', 'aPlus', 'video']. | |
| bsrMax | No | Maximum Best Sellers Rank. Example: 100000. | |
| bsrMin | No | Minimum Best Sellers Rank (lower = better). Example: 1. | |
| lqsMax | No | Maximum Listing Quality Score. No data in the source currently. | |
| lqsMin | No | Minimum Listing Quality Score. No data in the source currently. | |
| sortBy | No | Sort field | monthlySalesFloor |
| keyword | No | Search keyword | |
| pageSize | No | Page size | |
| priceMax | No | Maximum product price. Example: 99.99. | |
| priceMin | No | Minimum product price. Example: 9.99. | |
| dateRange | No | Aggregation window for metrics like monthly sales, revenue, and rating count. Null or '30d' — last 30 days (default). 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month. | |
| fbaFeeMax | No | Maximum FBA fee. Example: 15.00. | |
| fbaFeeMin | No | Minimum FBA fee. Example: 3.00. | |
| ratingMax | No | Maximum star rating (0.0-5.0). Example: 5.0. | |
| ratingMin | No | Minimum star rating (0.0-5.0). Example: 4.0. | |
| sortOrder | No | Sort direction: asc or desc | desc |
| subBsrMax | No | Maximum sub-category BSR. Example: 50000. | |
| subBsrMin | No | Minimum sub-category BSR. Example: 1. | |
| listingAge | No | Max product age: '30d', '90d', '180d', '1y', '2y'. Null = no limit. | |
| qaCountMax | No | Maximum Q&A count. Example: 100. | |
| qaCountMin | No | Minimum Q&A count. Example: 5. | |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| bsrGrowthMax | No | Maximum 7-day main-category BSR change (see bsrGrowthMin). | |
| bsrGrowthMin | No | Minimum 7-day main-category BSR change = rank 7 days ago − rank today; positive means the rank improved. bsrGrowthMin=1000 keeps products that moved up at least 1000 places. Negative allowed. About 70.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| categoryPath | No | Category hierarchy from root to current level (e.g., ['Electronics', 'Computers', 'Laptops']) | |
| fulfillments | No | Fulfillment filter. Example: ['FBA', 'FBM']. | |
| categoryScope | No | includeChildren (default): categoryPath matches the given levels, so every subcategory is included. exactOnly: the product's category path must end at the last given level. Ignored without categoryPath; exactOnly without categoryPath is rejected with category_scope_requires_category_path. | includeChildren |
| excludeBadges | No | Exclude products with these badges. Supported: ['aPlus', 'video']. | |
| excludeBrands | No | Brand names to exclude. Example: ['Generic']. | |
| includeBrands | No | Brand names to include. Example: ['Apple', 'Samsung']. | |
| excludeSellers | No | Seller names to exclude. | |
| includeSellers | No | Seller names to include. Example: ['Apple Store']. | |
| ratingCountMax | No | Maximum total rating count. Example: 10000. | |
| ratingCountMin | No | Minimum total rating count. Example: 50. | |
| sellerCountMax | No | Maximum number of sellers. Example: 20. | |
| sellerCountMin | No | Minimum number of sellers. Example: 1. | |
| excludeKeywords | No | Keywords to exclude from results. Example: ['refurbished', 'used']. | |
| monthlySalesMax | No | Maximum monthly sales floor. Units sold. Example: 5000. | |
| monthlySalesMin | No | Minimum monthly sales floor. Units sold. Example: 100. | |
| subBsrGrowthMax | No | Maximum 7-day sub-category BSR change (see subBsrGrowthMin). | |
| subBsrGrowthMin | No | Minimum 7-day sub-category BSR change (rank 7 days ago − rank today; positive = improved). Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| variantCountMax | No | Maximum number of product variants. Example: 50. | |
| variantCountMin | No | Minimum number of product variants. Example: 2. | |
| bsrGrowthRateMax | No | Maximum BSR growth rate as decimal. | |
| bsrGrowthRateMin | No | Minimum BSR growth rate as decimal. Example: -0.2 = 20% improvement. | |
| keywordMatchType | No | Keyword match type: 'fuzzy', 'phrase', or 'exact'. Null = fuzzy. | |
| onlyCategoryRank | No | If true, only return products ranked in their category BSR. | |
| packageSizeTypes | No | Package size tiers (US 2024-25 FBA tiers): smallStandard, largeStandard, largeBulky, extraLarge. Mostly inferred from weight alone (dimensions cover ~2% of products), so a light but long item can be classed smallStandard. About 31.4% of products have a tier. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| packageWeightMax | No | Maximum package weight in ounces (see packageWeightMin). | |
| packageWeightMin | No | Minimum package weight in ounces (page 'Item Weight' converted; same unit as /markets/search). About 31.4% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. | |
| monthlyRevenueMax | No | Maximum monthly revenue floor. Example: 50000.00. | |
| monthlyRevenueMin | No | Minimum monthly revenue floor. Example: 1000.00. | |
| grossMarginRateMax | No | Maximum gross margin rate, 0-1 (see grossMarginRateMin). | |
| grossMarginRateMin | No | Minimum gross margin rate, 0-1: (price − FBA fee) ÷ price; excludes referral fee and cost of goods. Products with unknown FBA fee are excluded. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. | |
| ratingFilterTarget | No | Choose whether rating-related filters apply to the current product or the most-rated variant. | |
| salesGrowthRateMax | No | Maximum sales growth rate as decimal. Example: 0.5 = 50% growth. | |
| salesGrowthRateMin | No | Minimum sales growth rate as decimal. Example: 0.1 = 10% growth. | |
| ratingToSalesRateMax | No | Maximum rating-to-sales rate as decimal. Example: 0.5. | |
| ratingToSalesRateMin | No | Minimum rating-to-sales rate as decimal. Example: 0.05. | |
| monthlyRatingCountMax | No | Maximum monthly new rating count. Example: 500. | |
| monthlyRatingCountMin | No | Minimum monthly new rating count. Example: 10. | |
| parentMonthlySalesMax | No | Maximum parent ASIN monthly sales floor. Units sold. | |
| parentMonthlySalesMin | No | Minimum parent ASIN monthly sales floor. Units sold. | |
| buyBoxSellerCountryCodes | No | Buy Box seller country codes, two uppercase letters each, e.g. ['CN', 'US']. About 88.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| monthlyRevenueGrowthRateMax | No | Maximum monthly revenue growth rate as decimal (see monthlyRevenueGrowthRateMin). | |
| monthlyRevenueGrowthRateMin | No | Minimum monthly revenue growth rate as decimal: today's monthlyRevenueFloor vs the same-basis value 30 days earlier, minus 1. About 3.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. |