# BugChorus — App Review Analyzer & Release Monitor (`reviewsignal/app-review-bug-detector`) Actor

Turn App Store and Google Play reviews into ranked issue clusters, traceable evidence, and guarded release comparisons. Export HTML, JSON, CSV, or Excel.

- **URL**: https://apify.com/reviewsignal/app-review-bug-detector.md
- **Developed by:** [BugChorus Team](https://apify.com/reviewsignal) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.44 / analyzed app-country report

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## BugChorus — App Review Analyzer & Release Monitor

Know what users are reporting after a mobile release without reading hundreds of reviews.

BugChorus turns public Apple App Store and Google Play reviews into ranked issue clusters, traceable review evidence, and a guarded version-over-version comparison. Use it for your own apps or any public competitor listing.

**$0.44-$0.50 per non-empty app-country report** · **No Apple, Google, or LLM API keys** · **One-time analysis or scheduled monitoring**

**[Run the preconfigured one-app example](https://apify.com/reviewsignal/app-review-bug-detector/examples/app-review-analyzer-one-app-check)**

![BugChorus app review analyzer](./assets/bugchorus-launch.png)

### What you learn from one run

| Question | What BugChorus returns |
| --- | --- |
| What are users repeatedly complaining about? | Ranked crash, login, billing, performance, ads, lost-data, feature, update, and UX issue clusters. |
| Does the newest observed version look worse? | A guarded comparison against the prior observed version, including sample sizes and negative-review rates. |
| Which reviews support the signal? | Traceable evidence with rating, date, app version, excerpt, and source link when available. |
| What changed since the last check? | In monitor mode, the number of genuinely new reviews since the saved baseline. |
| Can I use the results elsewhere? | A readable HTML/Markdown report plus structured data exportable as JSON, CSV, or Excel. |

The Actor returns `ALERT`, `WATCH`, `CLEAR`, or `INSUFFICIENT_DATA`. It uses `INSUFFICIENT_DATA` when there is not enough version-labeled review evidence for a responsible comparison.

### Start in under a minute

1. Open the **[one-app example](https://apify.com/reviewsignal/app-review-bug-detector/examples/app-review-analyzer-one-app-check)**.
2. Replace the example with a public App Store or Google Play URL.
3. Choose the storefront country and review window.
4. Click **Start** and open **HTML report** when the run finishes.

The public example is configured for one iOS app in one country with a `$0.51` maximum run charge.

Minimal input:

```json
{
  "appUrls": [
    "https://apps.apple.com/us/app/instagram/id389801252"
  ],
  "countries": ["us"],
  "daysBack": 30,
  "mode": "snapshot"
}
```

Google Play URLs, `ios:389801252`, and `android:com.example.app` references are also accepted.

### What the report looks like

![App Review Release Monitor report preview](./assets/report-preview.png)

Each report includes:

- app, platform, storefront country, store rating, and current observed version;
- reviews analyzed, issue-review count, and negative-review rate;
- top issue clusters with counts, share, severity, and version distribution;
- the strongest supporting review excerpts;
- current-versus-prior version sample sizes and rate difference;
- genuinely new reviews when stateful monitoring is enabled;
- direct links to the public store listing or review when available.

### Why use this instead of a raw review export?

A raw export gives you rows to read. BugChorus adds the analysis layer needed for a release decision:

- a shared issue taxonomy across iOS and Android;
- ranked evidence instead of an unprioritized text dump;
- a minimum-sample guard before making version-regression claims;
- a human-readable decision report for product, QA, or release meetings;
- structured output for dashboards, webhooks, APIs, and automation;
- saved monitor state for identifying reviews that are actually new.

Classification is deterministic. There is no model prompt, LLM key, token bill, or changing AI interpretation between runs.

### Best uses

- **Release checks:** investigate whether negative feedback increased after shipping a mobile update.
- **Issue discovery:** surface repeated crash, login, payment, performance, ad, or UX complaints.
- **QA prioritization:** attach review evidence to the issues most worth reproducing first.
- **Competitor monitoring:** watch public reviews for product gaps and recurring release problems.
- **Regional comparison:** analyze the same listing across up to five storefront countries.
- **Scheduled monitoring:** run a saved Apify task daily or weekly and route results into another workflow.

### How the analysis works

1. The Actor fetches recent public reviews from the selected stores and countries.
2. It normalizes ratings, review text, dates, versions, helpful votes, and source links.
3. It groups selected low-rating reviews into practical issue families and ranks their evidence.
4. When version samples are strong enough, it compares the newest observed version with the prior observed version.

The regression calculation uses all fetched ratings. `focusRatings` controls which ratings become issue clusters and supporting evidence.

A newer version observed in review data can take precedence when store metadata is stale during a staged rollout. Both compared versions must meet `minReviewsForRegression`, and the rate change must pass minimum-difference and statistical-signal checks.

### Input reference

| Input | Purpose | Default |
| --- | --- | --- |
| `appUrls` | Up to 20 App Store or Google Play URLs/IDs. | Required |
| `countries` | One to five two-letter storefront countries. | `us` |
| `language` | Google Play review language. | `en` |
| `daysBack` | Review age window from 1 to 365 days. | `30` |
| `maxReviewsPerAppCountry` | Maximum recent reviews fetched for each app-country target. | `300` |
| `focusRatings` | Ratings used for issue clusters and evidence. | `1`, `2`, `3` |
| `minReviewsForRegression` | Minimum reviews required for each compared version. | `5` |
| `mode` | One-time `snapshot` or stateful `monitor`. | `snapshot` |
| `stateKey` | Optional stable name for a monitor baseline. | Derived from apps |
| `includeRawReviews` | Include normalized review rows inside each report. | `false` |
| `maxEvidencePerIssue` | Maximum review examples retained per issue. | `3` |

### Output and integrations

| Output | Use |
| --- | --- |
| **Structured reports** | One dataset item per app-country target; export as JSON, CSV, or Excel. |
| **REPORT.html** | Browser-ready report for a product, QA, or release meeting. |
| **REPORT.md** | Portable summary for GitHub, Slack, Notion, or an issue tracker. |
| **OUTPUT** | Machine-readable run totals, verdict counts, failures, and monitor details. |

Save the input as an Apify task to schedule it. Use Apify's REST API, webhooks, integrations, or MCP support to send the normalized results into dashboards, alerts, or internal workflows.

### Stateful monitoring

Set `mode` to `monitor` and use the same `stateKey` on later runs.

- The first run creates a baseline and reports zero new reviews.
- Later runs compare fetched review IDs with that baseline.
- Separate `stateKey` values keep products, clients, or environments isolated.
- A scheduled Apify task can run the same monitor daily or weekly.

Use a different `stateKey` whenever you want a completely separate monitor history.

### Pricing

The `app-report` event is charged only after a successful app-country report containing at least one review is written.

| Apify buyer tier | Price per report |
| --- | ---: |
| Free / no discount | $0.50 |
| Starter / Bronze | $0.48 |
| Scale / Silver | $0.46 |
| Business / Gold | $0.44 |

Examples at the highest per-report price:

- 1 app × 1 country = up to `$0.50`
- 2 apps × 2 countries = up to `$2.00`
- 10 apps × 1 country = up to `$5.00`

Invalid targets and valid targets with no reviews do not trigger the `app-report` charge. Apify may display its very small standard Actor-start event separately. Set a maximum run charge if you need a hard spending ceiling.

### Limits and responsible interpretation

- Review signals are investigation evidence, not proof that a software release caused a defect.
- Confirm high-severity findings with telemetry, crash reporting, support tickets, and reproduction.
- Apple currently exposes at most 500 recent reviews per app and storefront through its public feed.
- The issue taxonomy is optimized for English text. Ratings and version statistics remain language-independent.
- Google Play fields and availability can vary by country, language, rollout, and upstream changes.
- The Actor reads public data only. It cannot access App Store Connect, Google Play Console, private analytics, crash logs, or customer records.
- It does not reply to reviews, modify store listings, or make release decisions automatically.

If one target fails, the run records a clear target-level error and continues with the remaining targets.

### FAQ

#### Do I need Apple, Google, or LLM credentials?

No. BugChorus reads public store listings and reviews, and its classification is deterministic.

#### Can I analyze competitor apps?

Yes. You can analyze any public App Store or Google Play listing available in the selected storefront.

#### Why does the report say `INSUFFICIENT_DATA`?

There were not enough version-labeled reviews for both compared versions. Increase the review window, fetch more reviews, or cautiously lower `minReviewsForRegression`. Issue clusters still work without a version comparison.

#### Why does the first monitor run show zero new reviews?

The first run establishes the baseline. New-review counts become meaningful on the second run using the same `stateKey`.

#### Does `ALERT` prove the newest release is broken?

No. It means the public review evidence is strong enough to investigate. Confirm it using your internal engineering and support data.

#### Can I export raw reviews?

Yes. Enable `includeRawReviews`. Leave it off when issue clusters and evidence excerpts are sufficient and you want smaller reports.

### Support

When reporting a problem, include the Apify run URL, public app URL, storefront country, and input settings. Never include account passwords, store-console credentials, private API keys, or customer data.

# Actor input Schema

## `appUrls` (type: `array`):

Apple App Store URLs, Google Play URLs, ios:123456789, or android:com.example.app. Maximum 20 apps per run.

## `countries` (type: `array`):

Analyze each app in these two-letter storefronts. Multi-country runs are useful for localization and regional regressions.

## `language` (type: `string`):

Two-letter language code used for Google Play. Issue classification is optimized for English review text in this version.

## `daysBack` (type: `integer`):

Only reviews this recent are analyzed.

## `maxReviewsPerAppCountry` (type: `integer`):

The newest reviews fetched before the date and rating filters are applied. Apple exposes at most 500 reviews per app and country.

## `focusRatings` (type: `array`):

The regression calculation still uses all fetched ratings. This selection controls issue clusters and evidence.

## `minReviewsForRegression` (type: `integer`):

Prevents strong release claims from tiny samples. Five is useful for small apps; ten or more is safer for high-volume apps.

## `mode` (type: `string`):

Snapshot analyzes the current window. Monitor also remembers review IDs in a dedicated Actor-created store so scheduled runs can identify genuinely new reviews.

## `stateKey` (type: `string`):

Optional stable name for the monitor state, for example my-production-apps. Leave blank to derive it from the app list.

## `includeRawReviews` (type: `boolean`):

Off by default to keep reports compact. Evidence examples and grouped issues are always included.

## `maxEvidencePerIssue` (type: `integer`):

Maximum quoted review examples retained for each issue cluster.

## Actor input object example

```json
{
  "appUrls": [
    "https://apps.apple.com/us/app/instagram/id389801252"
  ],
  "countries": [
    "us"
  ],
  "language": "en",
  "daysBack": 30,
  "maxReviewsPerAppCountry": 300,
  "focusRatings": [
    "1",
    "2",
    "3"
  ],
  "minReviewsForRegression": 5,
  "mode": "snapshot",
  "stateKey": "",
  "includeRawReviews": false,
  "maxEvidencePerIssue": 3
}
```

# Actor output Schema

## `reports` (type: `string`):

One normalized decision report for every successfully analyzed app and country.

## `htmlReport` (type: `string`):

A browser-ready launch and release risk report.

## `markdownReport` (type: `string`):

Portable text report for GitHub, Slack, Notion, or an issue tracker.

## `summary` (type: `string`):

Machine-readable counts, verdicts, errors, and monitor metadata.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "appUrls": [
        "https://apps.apple.com/us/app/instagram/id389801252"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("reviewsignal/app-review-bug-detector").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "appUrls": ["https://apps.apple.com/us/app/instagram/id389801252"] }

# Run the Actor and wait for it to finish
run = client.actor("reviewsignal/app-review-bug-detector").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "appUrls": [
    "https://apps.apple.com/us/app/instagram/id389801252"
  ]
}' |
apify call reviewsignal/app-review-bug-detector --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,reviewsignal/app-review-bug-detector"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cXN4UCubqco4YonG9/builds/PLHeehsf7KscpPMpP/openapi.json