openapi_v2_reviews_search
Search a product's reviews
Function
Return individual review texts with their AI-generated tags for one ASIN, page by page (default 10 per page, max 20). The reviews are those of the parent the ASIN belongs to, not only of that child ASIN. Filters: star rating range, verified purchase, Vine program, helpful vote count, review date range and mediaTypes; all filters combine with AND. mediaTypes=['image'] keeps reviews with at least one image — about 8% of stored reviews carry images and reviews added since 2026-08-30 currently carry none, so it mainly matches older reviews; video filtering is not offered, and on this endpoint videos[].url holds the video's cover image rather than a playable address. Tags are returned on each review but cannot be filtered on. Sort by recent, rating or helpfulVoteCount. At most 5000 reviews of a parent are read before filtering, so meta.total can be capped for very large parents. Reviewer identity is not returned. Billing: 1 credit per request.
Use cases
Use search to quote the reviews behind a finding — e.g. the low-star reviews of the month where /voc/trend shows a pain point rising. Use /voc/analysis for the aggregated demand profile and /voc/trend for how it changes over time; both return aggregates only. Use /realtime/reviews for the newest reviews currently shown on the product page.
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[TaggedReview]]",
"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
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number | |
| page | No | Page number (1-indexed). | |
| sortBy | No | Sort field: 'recent' (date), 'rating' (star rating), 'helpfulVoteCount' (vote count). | recent |
| dateEnd | No | Latest review date (inclusive, YYYY-MM-DD). Example: '2026-04-01'. | |
| pageSize | No | Results per page. | |
| vineOnly | No | If true, only return Amazon Vine program reviews. | |
| dateStart | No | Earliest review date (inclusive, YYYY-MM-DD). Example: '2025-01-01'. | |
| ratingMax | No | Maximum star rating (inclusive). Example: 3 for negative reviews. | |
| ratingMin | No | Minimum star rating (inclusive). Example: 1. | |
| sortOrder | No | Sort direction: 'desc' or 'asc'. | desc |
| mediaTypes | No | Media filter. The only value is 'image': keep reviews with at least one image. Omitted or empty means no media filter. About 8% of stored reviews carry images, and reviews added since 2026-08-30 currently carry none, so this filter mainly matches older reviews. Video filtering is not offered. | |
| verifiedOnly | No | If true, only return verified purchase reviews. | |
| helpfulVoteCountMin | No | Minimum helpful vote count. Example: 5. |