Get Reviews
get_reviewsRead-only
Reviews for any app over a window, filtered by storefront, star rating, text, or whether the developer has replied — plus the shape of the period: how many arrived per bucket, what they averaged, and where the app's pooled store rating stood while they did. Reviews exist for every app whether or not App Store Connect is connected, because they are read from the public store. This is the tool for "what are people complaining about": filter it and read the reviews yourself rather than asking for a summary. Every review says whether it can be answered (can_reply) and where an existing reply stands (reply_state); reply_to_reviews is what answers them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. | |
| from | No | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. | |
| limit | No | Max reviews, newest first. Default 25, capped at 200. The answer always says how many matched. | |
| app_id | Yes | Apptail app id. get_account for the user's own apps, search_apps for any other. Reviews are readable for any app in the store, including competitors. | |
| period | No | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. **This tool also takes `all`**, which is the app's whole review history and the only period that reaches a backlog older than three years. Reviews are kept for the life of the app and the console's own reviews screen has no date bound at all, so the ceiling above is about first-party analytics and not about these rows. Send `all` for "what have we never answered" and for anything asking about a review from years ago; the trend then buckets by quarter or year. | |
| rating | No | Only these star ratings, e.g. `[1, 2]` for the critical ones. Omit for all five. The `summary` counts are deliberately NOT filtered by this, so a call asking only for one-stars still learns how many reviews the period actually held. | |
| country | No | Only reviews from this storefront (e.g. de). Omit for every storefront, which is usually right — one storefront's reviews are a thin sample. Send it when `ratings.by_country` on get_app has pointed at a market, which is the follow-up that finds out why it is low. | |
| contains | No | Only reviews whose title or body contains this text, case-insensitively. Title as well as body, because a complaint is as often the headline as the paragraph. This is how you check a hypothesis — "crash", "subscription", "ads" — rather than reading everything. | |
| unanswered | No | Only reviews the developer has never replied to. False or omitted for all of them. Combined with `rating: [1, 2]` this is the work queue the console leads with — and **a backlog has no window**, so send `period: "all"` when you mean all of it. `summary.unanswered` is the whole-history count either way, and a list that is smaller than it is a windowed list, not a shorter backlog. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Reviews returned. | |
| total | Yes | Reviews matching the filters in this window. Larger than `count` when the list was capped. | |
| trend | Yes | The shape of the period. Compare `average_rating` with `store_rating` bucket by bucket: the first is the mood of what arrived, the second is the running total the store ranks on, and the gap between them is the finding. | |
| app_id | Yes | The app the reviews belong to. | |
| window | Yes | The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones. | |
| country | No | Storefront the list was narrowed to, or null for every storefront. | |
| replies | Yes | Whether replying is available to this account at all. Read it together with `can_reply` on each review: this is about the account's key, that is about the individual review having an App Store Connect id. Both must be true. | |
| reviews | Yes | The matching reviews, newest first, in the language they were written in. Read them; do not ask for a summary you can produce better yourself. | |
| summary | Yes | The period in figures. `arrived*`, `critical*` and `average_rating*` are flows *in the window*; `all_time`, `unanswered` and `store_rating*` are the app's standing position and ignore it. Mixing the two is how "we got 12 reviews and have 400" becomes one number. | |
| app_name | No | Its name. | |
| filtered | Yes | True when any of `country`, `rating`, `contains` or `unanswered` narrowed the list. Worth saying out loud: "no reviews" under a filter is not "no reviews". | |
| truncated | Yes | True when `count` is below `total`. Say the list is a sample rather than presenting it as everything that was written. | |
| console_url | No | The app's Reviews screen in the console. |