--- title: "How reviews work" description: "Collect App Store, Google Play, Trustpilot and Google reviews of your product or a competitor's as mentions of a keyword, with the stars and the owner's reply." canonical: https://docs.mentio.dev/platforms/reviews markdown: https://docs.mentio.dev/platforms/reviews.mdx --- # How reviews work Collect App Store, Google Play, Trustpilot and Google reviews of your product or a competitor's as mentions of a keyword, with the stars and the owner's reply. A keyword can collect the reviews of what it stands for. Add a review page to the keyword's `reviewSources` and every new review there becomes a mention of the keyword, with its star rating, whether or not the review says the name. Most reviews never do ("crashes when I upload a photo"), which is why a review platform is not searched by the keyword's term the way the other platforms are. | Platform | `platform` | Paste | Per country | | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------ | --------------------------------- | | [App Store](/platforms/appstore) | `appstore` | The app's App Store link | Yes, `countries` | | [Google Play](/platforms/googleplay) | `googleplay` | The app's Google Play link | Yes, `countries` and a `language` | | [Trustpilot](/platforms/trustpilot) | `trustpilot` | The company's page, `trustpilot.com/review/` | No, one page | | [Google reviews](/platforms/googlemaps) | `googlemaps` | The place's Google Maps link (a `maps.app.goo.gl` share link works), or its Place ID | No, one place | A keyword is its term, its review sources, or both: | `platforms` | `reviewSources` | The keyword collects | | ---------------- | --------------- | ---------------------------------------------- | | `null` or a list | none | posts that contain the term (as before) | | `null` or a list | some pages | those posts, and every review on the pages | | `[]` | some pages | only the reviews: the term is searched nowhere | A keyword with `platforms: []` and no review sources would track nothing, so the API refuses it (400 `validation_error`). Reviews land in the same feed as everything else: they are triaged, filtered, exported, sent to alert rules and counted in analytics like any mention. The platform is `appstore`, `googleplay`, `trustpilot` or `googlemaps`. ## Connect a review page to a keyword Pass `reviewSources` when you create the keyword, or later with `PATCH /v1/keywords/{id}`. Each entry is a link, or a `platform` and an `id`: ```bash curl -X POST https://api.mentio.dev/v1/keywords \ -H "Authorization: Bearer $MENTIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "term": "Notion", "kind": "brand", "reviewSources": [ { "url": "https://apps.apple.com/us/app/notion-notes-docs-tasks/id1232780281", "countries": ["us", "gb"] }, { "url": "https://play.google.com/store/apps/details?id=notion.id", "language": "en" }, { "url": "https://www.trustpilot.com/review/notion.so" } ] }' ``` | Field | What it is | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | The page's link: an App Store or Google Play app, a Trustpilot page, a Google Maps place (a `maps.app.goo.gl` share link is opened for you). | | `platform`, `id` | Instead of `url`: `appstore` with the app's digits, `googleplay` with the package name (`notion.id`), `trustpilot` with the domain (`notion.so`), `googlemaps` with a Place ID (`ChIJ...`). | | `countries` | App Store and Google Play only: storefronts to read, two-letter codes, at most 20. Default: the one in the link, else `us`. Reviews are stored per storefront, so an app reviewed mostly in Germany needs `de`. Trustpilot and Google Maps have one page for everyone and take none. | | `language` | Google Play only: the language of the reviews to read (`en`, `es`, `pt-BR`). Google Play answers one language at a time. Default: the link's `hl`, else `en`. | A keyword names at most 10 review pages. `PATCH` replaces the whole list; `[]` disconnects them all, and the reviews already collected stay. The keyword comes back with a `reviewSources` array: each page's `platform`, `id`, `url`, `countries`, `language` and `connectedAt`. A keyword can name a competitor's app too. A `competitor` keyword on a rival's app, with an alert rule for `ratings: [1, 2]`, is a daily list of their unhappy users. To collect only those reviews, not every post that names the rival, send `"platforms": []`: ```bash curl -X POST https://api.mentio.dev/v1/keywords \ -H "Authorization: Bearer $MENTIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "term": "Linear", "kind": "competitor", "platforms": [], "reviewSources": [{ "url": "https://apps.apple.com/us/app/linear/id1645587184" }] }' ``` A keyword costs the same $5 a month either way; its reviews bill like any mention. ## What a review looks like A review is a regular mention with one more concern, `review`: ```json "review": { "rating": 1, "ratingMax": 5, "title": "Logged me out after the update", "version": "4.12.0", "country": "us", "verified": null, "response": "Sorry about that! Fixed in 4.12.1.", "responseAt": "2026-09-25T18:00:00.000Z", "app": { "platform": "appstore", "id": "1232780281", "url": "https://apps.apple.com/us/app/id1232780281" } } ``` `review` is `null` on every other post. `response` is the owner's or developer's reply (the App Store's feed carries none); `title` exists on the App Store and Trustpilot; `version` on the app stores; `verified` on Trustpilot; `country` is the storefront on the app stores and the reviewer's country on Trustpilot. `app` names the review page, whatever the platform. * **Relevance:** a review always counts as relevant, since you chose the page. Its relevance is set by the keyword's kind: 95 for `brand`, 75 for `competitor`, 60 for `topic`. * **Sentiment:** from the stars, not the text: 4 and 5 are positive, 3 is neutral, 1 and 2 are negative. * **Tags:** the classifier still reads the text for the intent tags, so a review can carry `bug_report`, `churn_intent`, `pricing`, `praise` and the rest, plus its language. * **Date:** `post.publishedAt` is when the review was written, not when Mentio found it. ## Filter reviews `ratings` takes a list of star ratings and keeps only reviews that have one of them. It works on `GET /v1/mentions`, the CSV export, views and alert rules. Any post that is not a review fails it. ```bash curl "https://api.mentio.dev/v1/mentions?platforms=appstore,googleplay&ratings=1,2" \ -H "Authorization: Bearer $MENTIO_API_KEY" ``` The CSV export adds `rating` and `app_id` (the page's id) as its last two columns. ## Report on reviews `GET /v1/analytics/reviews` sums up your reviews over a window. It takes the same window as the other analytics reports: `range`, `from` and `to`, `timezone`, `keywordIds`, `platforms` and `compare`. It also takes `bucket` (`day` or `week`). ```bash curl "https://api.mentio.dev/v1/analytics/reviews?range=30d&compare=true" \ -H "Authorization: Bearer $MENTIO_API_KEY" ``` * **`totals`:** how many reviews, the average stars, the count for each star from 1 to 5, how many have a reply, and how many 1 and 2 star reviews are still open. A review two of your keywords match counts once. * **`tags`:** the tags on the 1 and 2 star reviews, most frequent first. This is what the unhappy reviews are about. * **`pages`:** the same numbers for each review page, plus its average stars by day or by week. With `compare=true`, `previous` holds the period of the same length just before the window. The CLI runs it as `mentio analytics:reviews` and the MCP server as `get_reviews_report`. In the dashboard it is the **Reviews** page. ## How reviews are collected * **Once a day** per page (and per storefront on the app stores), shared by every workspace that names it. * **The last 30 days, free, at once:** connecting a page (or adding a storefront or a language) brings its newest 100 reviews of the last 30 days. Those are not billed and never sent as instant alerts; they reach the feed and the daily digest. Free means reviews written before your workspace FIRST connected that page: disconnecting and reconnecting it, or deleting the keyword and creating it again, brings no new free reviews, and two keywords on one page share one free batch. * **After that, each new review bills like any mention.** The same review seen in two storefronts is one mention, and an edited review is not counted again. * **Each storefront is its own.** A keyword gets the reviews of the storefronts it names only, never those another keyword reads; a country added later starts on the day it is added, with its own free look-back. * **A muted keyword** stops collecting; unmuting it after a day or more reads back at most a day, like every platform. The monthly mention cap applies to new reviews like to any mention, which is what bounds the bill for a very busy app or place; the free look-back does not count against it.