---
title: "Reviews: stars over a window, per review page"
method: GET
path: "/v1/analytics/reviews"
tags: ["Analytics"]
---

# Reviews: stars over a window, per review page

`GET /v1/analytics/reviews`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/analytics/reviews`
- Auth: HTTP bearer

The reviews a keyword collects (App Store, Google Play, Trustpilot, Google Maps): count, average stars, distribution, replies and open 1-2 star reviews, for the workspace and per review page with a series of average stars per `bucket`, plus the tags the unhappy reviews carry. A review matched by two keywords counts once. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.

## Query parameters

- `range` '7d' | '30d' | '90d' | '365d': Preset window ending today. Ignored when from or to is given. Default 30d.
- `from` string: First day, YYYY-MM-DD, inclusive, in `timezone`.
- `to` string: Last day, YYYY-MM-DD, inclusive, in `timezone`. Default today.
- `keywordIds` string[], nullable: Only these keyword ids. Repeatable, or comma-separated; omit for every keyword.
- `platforms` string[]: Only these platforms. Repeatable, or comma-separated; omit for every platform.
- `compare` boolean: true adds the period of the same length right before the window as `previous`.
- `timezone` string: IANA zone the days are cut in (Europe/Madrid). Default UTC. One offset, the zone's at the end of the window, applies to the whole window.
- `bucket` 'day' | 'week': Series bucket: day (default up to 90 days) or week.

## Response `200`

The report, with `previous` when comparing

- ReviewsReport
  - `window` object, required: The window the report covers.
    - `from` string, required: First day, inclusive.
    - `to` string, required: Last day, inclusive.
    - `days` integer, required: Length of the window in days.
    - `timezone` string, required: IANA zone the days were cut in.
    - `bucket` 'day' | 'week', required: How the page series are cut: day up to 90 days, else week, unless asked.
  - `totals` object, required
    - `reviews` integer, required: Reviews published in the window; a review matched by two keywords counts once.
    - `averageRating` number, nullable, required: Average stars, one decimal; null with no reviews.
    - `distribution` object, required: Reviews per star rating.
      - `1` integer, required
      - `2` integer, required
      - `3` integer, required
      - `4` integer, required
      - `5` integer, required
    - `responded` integer, required: Reviews carrying the owner's or developer's reply (the App Store's feed has none).
    - `openNegative` integer, required: 1 and 2 star reviews nobody has marked done or ignored yet.
  - `tags` object[], required: Intent and topic tags on the 1 and 2 star reviews, most frequent first: what the unhappy ones are about.
    - `tag` string, required
    - `count` integer, required
  - `pages` object[], required: One row per review page with reviews in the window, most reviewed first.
    - `reviews` integer, required: Reviews published in the window; a review matched by two keywords counts once.
    - `averageRating` number, nullable, required: Average stars, one decimal; null with no reviews.
    - `distribution` object, required: Reviews per star rating.
      - `1` integer, required
      - `2` integer, required
      - `3` integer, required
      - `4` integer, required
      - `5` integer, required
    - `responded` integer, required: Reviews carrying the owner's or developer's reply (the App Store's feed has none).
    - `openNegative` integer, required: 1 and 2 star reviews nobody has marked done or ignored yet.
    - `platform` 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps', required: appstore (Apple App Store), googleplay (Google Play), trustpilot (a company's Trustpilot page) or googlemaps (a place's Google reviews).
    - `id` string, required: The page's id: app id, package name, Trustpilot domain, Place ID or cid.
    - `url` string, required: The review page.
    - `series` object[], required: Reviews and average stars per bucket, oldest first, every bucket present.
      - `date` string, required: Bucket start, YYYY-MM-DD.
      - `reviews` integer, required
      - `averageRating` number, nullable, required: Average stars, one decimal; null with no reviews.
    - `previous` object, nullable, required: The period of the same length right before the window, with compare=true; else null.
      - `reviews` integer, required
      - `averageRating` number, nullable, required: Average stars, one decimal; null with no reviews.
  - `previous` object, nullable, required: Totals for the period right before the window, with compare=true; else null.
    - `reviews` integer, required: Reviews published in the window; a review matched by two keywords counts once.
    - `averageRating` number, nullable, required: Average stars, one decimal; null with no reviews.
    - `distribution` object, required: Reviews per star rating.
      - `1` integer, required
      - `2` integer, required
      - `3` integer, required
      - `4` integer, required
      - `5` integer, required
    - `responded` integer, required: Reviews carrying the owner's or developer's reply (the App Store's feed has none).
    - `openNegative` integer, required: 1 and 2 star reviews nobody has marked done or ignored yet.

## Other responses

- `400`: Invalid query
- `401`: Missing or invalid API key

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)