query_reviews
Amazon REVIEWS and RATINGS of the seller's products, per ASIN and marketplace (Amazon Data Kiosk): the reviews received over a period, the critical ones (3 stars or less), the star rating and the ratings count Amazon displays, and a review rate. The same route as the app's Reviews columns and modal, on the Seller Central (3P) accounts of the call. Metric keys are their OWN universe, not list_metrics keys: reviews, critical_reviews, critical_review_share, review_units, review_rate, rating, ratings, rating_week_end, rating_marketplace (describe_metric defines each). ⚠️ READ BEFORE ANSWERING. (1) The COUNTS (reviews, critical_reviews, critical_review_share, review_units, review_rate) exist only on the marketplaces where Amazon serves them: US, CA, MX, BR. Everywhere else, Europe included, they are null (n/a), never 0. (2) A review belongs to the ASIN: every new rating from ANY buyer of the ASIN, written or not (the product page lists the written ones only), not only this seller's buyers. So there is no SKU grain (a SKU or tag filter reads its ASIN's reviews), and two seller accounts carrying one ASIN carry the same reviews: never add up the rows of groupBy sellerAccount yourself, summary.total counts each ASIN once. (3) Amazon serves a day of reviews about 3 days late, and its last served day is still filling: the answer's reviews_served_from and reviews_served_to are the first and last days served, reviews_complete_to the last complete one. Compare periods, or compute a pace or a rate, over complete days only. In a series a bucket without a review reads null: no review on a served day, not known on the others. (4) rating and ratings are the state the product page displays (ratings is Amazon's count for the ASIN worldwide since its launch, not the period's), read at the period end, never a period total. A row covering several marketplaces reads its top-selling one (rating_marketplace), never a blend; never add ratings up across rows. Amazon keeps no rating history: Nova's is its own reads, which started on 2026-10-01 (per week, the first document closes on 2026-09-26); a bucket before the first read is empty, never 0. (5) review_rate = the ASIN's reviews (all buyers) per 100 units sold by THIS account (review_units): meaningful only where the seller is the ASIN's only seller (its own brand), meaningless on a reseller's shared ASINs (it can exceed 100). (6) NO comparison mode: call once per period. (7) groupBy is EITHER an entity grain (parentAsin, marketplaceParentAsin, childAsin, marketplace, sellerAccount) OR a time grain (day, week, month), never both: for one product's series, filter on it and group by the grain. Per day, week or month: the flows (reviews, critical_reviews, critical_review_share). Per day (as read each day) or week (Amazon's week documents), never month, and in a call of their own: rating, ratings, rating_week_end. Never per time bucket: review_units, review_rate, rating_marketplace. A series comes whole and in date order, one row per bucket: no sortBy, limit or offset, and 1000 buckets at most (over a long period, group by week or month). 🔒 HISTORY: every plan reads the whole history, except a read of review_units or review_rate by an organization on its free trial (no subscription yet, an abandoned checkout included, or no active subscription while its 14-day trial still runs): nothing before its floor is served then, its reviews included, and the answer carries dataFloor, that ISO day, when Nova can state the floor that applied. A paying plan, and a plan cancelled after its trial ended, read the whole history. Vendor Central (1P) accounts have no reviews here: Amazon serves vendors no rating and no review count.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page of an entity grouping, 1 to 1000 (default 50). Not with a time grain: a series comes whole. | |
| offset | No | Row offset for paging an entity grouping (default 0). Not with a time grain. | |
| period | Yes | REQUIRED. The flows are summed over it; rating and ratings are the state at its end. No comparison period: call once per period. | |
| reason | No | One sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used. | |
| sortBy | No | A metric of `metrics` to rank the rows of an entity grouping by (e.g. "reviews"); rating_week_end and rating_marketplace sort alphabetically. Not with a time grain: a series comes in date order. | |
| filters | No | Restrict the read. Omit for every product of the accounts. | |
| groupBy | No | EITHER an entity grain: parentAsin (a variation family, in every marketplace where it exists), marketplaceParentAsin (a family on ONE marketplace, keyed '<marketplaceId>:<parentAsin>': the app's parent rows), childAsin, marketplace or sellerAccount; OR a time grain: day, week or month (one row per bucket, the whole series). Omit, or null, for one total row. | |
| metrics | Yes | Reviews metric keys: reviews, critical_reviews, critical_review_share, review_units, review_rate, rating, ratings, rating_week_end, rating_marketplace. Their own universe: NOT list_metrics, ads or SQP keys. A natural name that means exactly one of them (e.g. "review rate") is resolved and echoed under `metricAliases`. | |
| accounts | No | Restrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id. | |
| sortOrder | No | desc (default) = biggest first, asc = smallest first. Not with a time grain. |