Low Rating Review Analyzer — CSV & JSON

Turn reviews you own or are authorized to process into an inspectable complaint summary. Try a fixed CC0 synthetic demo, paste JSON, paste a CSV export, or upload a CSV/JSON file through the Apify input form. Select a star range, language and review limit. The Actor delivers one analysis record per selected review and a summary with candidate themes, example review IDs and the size of the analyzed sample.

Price: $0.001 per accepted delivered result ($1 per 1,000 results), plus separately metered official Apify OpenRouter gateway usage. Valid unclassified results are included in the result fee. The review event covers the record and its contribution to the summary; there is no Actor-start event or additional dataset-item event for this Actor. Gateway usage is charged separately through Apify, so the result fee is not an all-inclusive price. No separate model API key or proxy is required. Check the current Apify pricing and spending controls before running; the review-event allowance alone does not guarantee total spend including the gateway.

A paid Apify plan is recommended. Apify's AI-agent documentation says free-tier accounts may be blocked by gateway anti-fraud protections. The official OpenRouter gateway pricing also states that free-tier users pay 10× the gateway usage rate charged to paying users, with usage rounding. These are gateway terms, separate from this Actor's result fee; check the linked current terms for your account.

Who this is for

Product managers, merchants and customer-experience teams analyzing their own product feedback, or a competitor-review export whose reuse is authorized. This is a processing tool for a supplied dataset. It does not provide a licensed review database, fetch Amazon review pages, bypass access controls, or promise coverage of every e-commerce site.

Use one product or a coherent comparison group per run. If you combine products, the summary describes that combined submitted sample. A low star rating and a candidate theme do not establish that a product is defective.

Quick start

1. The default Built-in synthetic demo processes five original CC0 example reviews only; it never accepts or sends your own comments or files. Select JSON reviews, Paste CSV, or Upload CSV/JSON to analyze customer data.
2. For your own reviews, affirm both that you have processing rights and that you permit cleaned review text to be processed through Apify → OpenRouter → Azure hosting of the OpenAI model. These boxes remain unchecked until you select them. The built-in fixed synthetic demo requires neither customer-data consent because it processes no customer data nor third-party review source.
3. Keep the default 1–3 stars, choose Automatic detection, and set the maximum reviews you want to analyze.
4. Set a run spending limit and run the Actor.
5. Open Analyzed reviews in the Dataset and Complaint themes and sample size in the run Output tab. The readable report is also linked there.

Built-in synthetic demo and daily Store checks

The preselected inputMode: "demo" runs a fixed five-review CC0 sample bundled into the Actor, not data entered into another field. The generated Dataset is non-empty under the normal 1–3-star filter and the run is designed to complete well within Apify's daily Store QA time limit. This mode uses the disclosed model gateway and may incur result and gateway charges; there is no all-inclusive free AI inference promise. No customer-data rights checkbox or customer-data AI consent is assumed or auto-checked, because no user data is processed in demo mode. Demo mode rejects non-empty reviews, csvText, or reviewFileUrl instead of silently discarding them; switch modes and affirm both permissions before processing your own data.

Minimal JSON input

{
  "inputMode": "json",
  "rightsConfirmed": true,
  "aiProcessingConfirmed": true,
  "reviews": [
    {"id": "review-001", "rating": 1, "text": "The handle broke after two days of normal use.", "language": "en"},
    {"id": "review-002", "rating": 2, "text": "The hinge snapped during the first week.", "language": "en"}
  ],
  "minRating": 1,
  "maxRating": 3,
  "language": "auto",
  "maxReviews": 1000
}

CSV input

id,rating,text,date,helpfulVotes,language
review-001,1,"The handle broke, even with normal use.",2026-09-01,3,en
review-002,2,"The hinge snapped during the first week.",,,en

Set inputMode to csv and paste this text into csvText. Commas inside a field and multiline text must be quoted according to CSV rules. UTF-8 BOM, CRLF/LF line endings, comma/semicolon/tab delimiters and empty optional cells are supported. There is no XLSX, ZIP, PDF, NDJSON or HTML-page input in this release.

File upload

Set inputMode to upload and use reviewFileUrl in the form. The upload editor produces an Apify key-value-store record URL. Only direct HTTPS URLs of this form are accepted:

https://api.apify.com/v2/key-value-stores/STORE_ID/records/FILE_KEY

The file must be UTF-8 CSV or JSON. A JSON file may contain a review array or an object containing only {"reviews": [...]}. Set fileFormat if auto detection is unsuitable. Arbitrary file hosts, review-page URLs, login pages and redirects are rejected. If an uploaded storage record redirects, paste its CSV/JSON content or upload a smaller directly served file. The Actor uses its limited run token only for the verified Apify API origin; it never requests a third-party review API.

Export column names

Your export may use different headers. Configure a canonical field → source column mapping:

{"id":"review_id","rating":"stars","text":"body","date":"created_at","helpfulVotes":"helpful_count"}

Mapping works for both CSV headers and top-level JSON fields. Nested export objects must be flattened first. Each canonical field needs a distinct source column. Unmapped fields use the exact canonical name.

Input fields

Field	Default / requirements	Meaning
inputMode	demo in the Apify form; direct unspecified-mode parser calls still require customer rights	demo (bundled five CC0 examples), json, csv, or upload
reviews	JSON array	Used only in JSON mode; empty arrays are valid
csvText	CSV string	Used only in CSV mode; header row required
reviewFileUrl	Apify upload URL	Used only in upload mode
fileFormat	auto	auto, csv, or json for an uploaded file
rightsConfirmed	false; must be true for user CSV/JSON	You own or are authorized to process the submitted customer data; fixed demo is exempt
aiProcessingConfirmed	false; must be true for user CSV/JSON	You consent to cleaned customer text being processed through the model gateway; fixed demo is exempt
minRating, maxRating	1, 3	Inclusive bounds on a 1–5 star scale
language	auto	auto, en, es, fr, de, or tr
maxReviews	1000	1–10,000 valid, unique, selected reviews
minThemeReviews	2	2–50 distinct reviews required to label a theme recurring
fieldMapping	{}	Canonical field to export header/key mapping
csvDelimiter	,	Comma, semicolon, or tab

Review fields and missing data

Only text and rating are required for an analyzable record. Rating must be finite and in 1–5; numeric strings in CSV are accepted. Empty/non-text reviews and malformed ratings are skipped and counted. This is not a conversion tool for 0–10 ratings.

Source field	Output behavior
id	Optional sourceReviewId; absent or invalid values are omitted
date	Optional supplied ISO date (YYYY-MM-DD) or timezone-qualified timestamp; invalid dates are omitted with a warning
rating	Selected source rating, never a predicted sentiment score
text	Review text after documented privacy and export-safety processing
helpfulVotes	Optional non-negative integer; a supplied zero is preserved
language	Optional source language tag; language codes such as en-US normalize to en
productId, source	Optional non-personal product/source labels, also used for duplicate scope

Every result has a stable internal reviewId and the original one-based inputRow. Internal IDs let theme examples reference records without inventing missing source IDs.

The same source ID is counted once within its source/product scope. When an ID is absent, identical normalized text and rating in that scope count once. Different supplied IDs remain separate evidence even when the text repeats. The first valid selected occurrence is retained; conflicting duplicates do not silently replace it.

How the complaint analysis works

The engine sends cleaned review text and a batch ordinal to the fixed official Apify OpenRouter gateway for openai/gpt-4.1-mini, restricted to Azure hosting. Source review IDs, product/source labels, ratings, dates, helpful counts and structured person/profile fields are not part of the model payload. No separate model API key is required; the gateway uses the Actor's Apify integration.

The request restricts provider routing to Azure, requires the zero-data-retention routing policy, denies provider data collection and disables provider fallback. These are request requirements, not a blanket promise that no system stores data. If the required route is unavailable, the provider request fails, the reported model/provider identity does not match, or a response violates the required classification schema, the run fails closed. The Actor does not automatically retry model requests or switch providers.

The model returns theme IDs. The backend supplies evidenceType: "full_review" and an evidenceReviewId referencing the corresponding Dataset record. The complete cleaned review text is the authoritative context for assessing each candidate theme. Summary exampleReviewIds point to those same records. The Actor does not ask the model to produce evidence quotations or excerpts, and provides no exact-quotation guarantee. Read the full review before treating a candidate category as an actionable complaint.

Candidate categories cover breakage/durability, functionality, battery/power, size/fit, material quality, delivery, packaging, missing parts, description mismatch, customer support, price/value and odor. Categories can overlap. A review contributes at most once to each theme, even if it repeats a complaint.

Supported analysis languages: English, Spanish, French, German and Turkish. They are not guaranteed to have identical coverage. Automatic language identification is heuristic and marked tentative. A supplied language is a declaration, not a model confidence score. Unsupported languages remain visible with uncertainty and no unsupported-language interpretation. Mixed or unidentified text carries warnings. The fixed model and supported languages do not imply verified accuracy for every dialect, export or review length.

When a specific input language is selected, known other languages and detected mixed text are excluded. Undetermined text is analyzed using a disclosed input_assumption and uncertain language confidence. For reliable selection, include the source language field.

All theme matches have confidence: "tentative". Short reviews, indirect language, sarcasm, comparisons, spelling variation and unfamiliar wording can be missed or misunderstood. A review with no matched theme is unclassified, not positive. This Actor does not discover arbitrary new categories, verify causation, certify product defects or estimate all-customer complaint rates.

Outputs

Default Dataset: one review_analysis record for each accepted delivered review. It includes the complete cleaned text, available source metadata, language provenance, candidate themes with backend-assigned full-review evidence IDs, themeIds and warnings. Export formats are available through normal Apify Dataset controls.

Default Key-value Store:

• SUMMARY: JSON with sampleSize, selected-language counts, rating counts, recurring/isolated candidate themes, theme counts and examples, unclassified count, exclusions, input limits, actual SDK charging counters and modelProcessing usage information.
• SUMMARY.md: a readable theme table and limitations.
• RUN_STARTED: a small lifecycle marker preventing duplicate processing if a completed or interrupted run is resurrected.

Every theme contains reviewCount, sampleSize, shareOfAnalyzedReviews, isRecurring, exampleReviewIds and available exampleSourceReviewIds. The denominator is the delivered analyzed sample. Filtered, invalid, duplicate and budget-excluded reviews do not enter that denominator. A size of 10 does not describe 10 random buyers; it describes 10 submitted records that reached the output. Overlapping shares may sum above 100%.

SUMMARY.modelProcessing reports attempted model calls, reported prompt/completion tokens, reported model cost and incomplete-usage calls, together with the configured and observed model/provider metadata. Reported model cost is not the final Apify invoice. Gateway plan multipliers, rounding and other gateway/platform charges can make the billed amount different. Failed requests can have unknown or separately billed usage. Inspect the actual Apify usage and charge receipts when reconciling costs.

Privacy and data rights

The Actor ignores structured person/profile fields such as author, reviewer name, username, profile URL and follower information. It removes known source-provided author/reviewer names when they occur in the review text, and redacts recognizable email addresses, phone-like contacts, URLs and handles. It does not use those attributes in classification or log raw input text. Formula-like text is prefixed with an apostrophe to reduce spreadsheet export risk.

Pre-anonymize free text. A rule-based redactor cannot reliably identify every person name, address or other personal detail that appears only in prose. Redaction is best effort, not a guarantee of anonymization. Source INPUT remains in your run storage under Apify's controls; cleaning output does not erase the original uploaded file. Manage your own input/output retention and access.

External AI processing requires aiProcessingConfirmed: true. Cleaned review text leaves the Actor through the official Apify OpenRouter gateway, is routed through OpenRouter, and is processed by openai/gpt-4.1-mini hosted on Azure. Only cleaned text and an ordinal are supplied as review data. Cleaning can miss prose-only personal details, so this payload can still contain personal information unless you remove it beforehand. Confirm that your rights and lawful basis cover this processing path, including any applicable transfer and retention obligations.

The Actor requests strict provider zero-data-retention routing, data_collection: "deny", Azure-only hosting and no provider fallback. This does not erase original Apify INPUT/uploads or establish a universal zero-storage guarantee across Apify, OpenRouter, Azure/OpenAI, network infrastructure and your own exports. Review the applicable provider terms and manage input/output retention and access. No personal profiles or external review databases are requested. Public visibility of a review does not itself establish permission for your intended reuse. The Apify Standard Actor Contract applies; this README does not replace it.

Limits, failures and billing

• Maximum source file: 10 MiB; maximum source rows: 50,000; maximum CSV columns: 200; maximum review text: 10,000 characters; maximum accepted reviews: 10,000. Unused CSV columns are discarded before row objects are created.
• Bad run-level configuration or malformed CSV/JSON fails the run with zero review events. Invalid individual records are skipped and counted.
• Empty valid input and no-match filters finish with zero review events and an empty summary. Unclassified but valid selected reviews are delivered and charged because they were processed.
• The Actor checks the remaining spending limit before model inference. The SDK then saves affordable rows and charges review-analyzed. The summary uses the delivered subset.
• Gateway inference incurs separately metered gateway usage before review rows are delivered. A provider or response-validation failure can therefore leave gateway costs without successful review output. Review-event receipts alone do not represent the full run cost.
• Provider-routing, identity, network and classification-schema errors fail the run closed. There are no automatic model retries or provider fallbacks; inspect existing outputs and charges before choosing to start a new run. The review-event allowance alone is not a guarantee of total spend including gateway usage.
• A limit-truncated sample has status: "limited". The input maxReviews and run spending limit are independent caps.
• Automatic restart is disabled. Resurrecting a started run fails closed instead of reprocessing it. Start a new run when needed; a new run is a new analysis and can incur new charges.
• Storage and billing are not a distributed transaction. On an infrastructure error, inspect existing Dataset rows and charge events before retrying; the error summary identifies incomplete reconciliation. Owner validation runs are not customer revenue.

Validation and known errors

Release validation used original synthetic reviews and fixed reference labels, rather than real customer data. The production runtime passed ten cloud cases, including the operational benchmark below; all 1,137 delivered review rows and ten summaries validated against their production schemas. JSON, pasted CSV and native-upload runs delivered the same 34 selected review IDs and theme IDs. One Turkish review's model_uncertain warning varied between those runs, so identical input and temperature zero do not promise identical uncertainty flags.

Fixture	Reviews scored	Correct theme assignments	Extra theme assignments	Missed reference themes
Additional 25-review fixture	23	17	0	0
Development fixture	30	27	0	3

The two other additional-fixture reviews were vague and marked uncertain, outside the scored subset. The implementation agent did not receive that fixture's text or reference labels, but aggregate earlier failures informed development; this is not an untouched external benchmark. On the development fixture, two implicit price/value themes and one reference functionality theme associated with a broken zipper were missed. The reference labels were kept unchanged; these misses remain disclosed. Theme-assignment counts differ from review counts because a review can have multiple themes or none.

Three prompt-boundary cases passed without extra themes or outputting the synthetic name/email used in those checks. 88 active unit tests passed both locally and on the deployment server; five retired-model tests were skipped and are excluded from that count. These checks support the tested input/output and failure contracts. The small synthetic fixtures do not establish general accuracy, real-world complaint rates or equal quality across languages and review styles.

Measured 1,000-review workload

A real Apify run on 2026-10-10 processed 1,000 original synthetic English reviews with distinct source IDs, averaging about 85 characters each. This repeated-pattern workload measures operation and cost; it is not a semantic-quality test of 1,000 independent customer reviews.

Measurement	Result
Delivered rows / review events / sample size	1,000 / 1,000 / 1,000
Runtime	265.054 seconds (about 4.4 minutes)
Allocated / peak memory	256 MiB / 81.95 MiB
Model calls	100
Reported prompt / completion tokens	93,001 / 19,000
Model-reported cost	USD 0.0676004
Settled parent-run usage	USD 0.0141226

During the separately observed FREE-account benchmark interval, account usage increased by approximately USD 0.69896, including a USD 0.68100 increase in its paid-Actor component. The release process started no other model run in that interval. Monthly accounting can include background storage and delayed charges, so these are account observations, not an itemized customer invoice or a finding about customer/creator cost allocation. The owner test did not generate customer revenue.

Under the gateway pricing snapshot used for this release, calculated paid-tier usage-event charges alone for that model usage would be approximately USD 0.06761–0.06860, excluding startup fees. The exact startup-event count is unverified. The Actor result fee would be USD 1.00, separately from gateway usage. Do not add the model-reported cost, gateway component and total-account increase together: they overlap. Longer reviews, other languages, failures, account plans and future rates can change cost and duration. These figures do not establish an all-inclusive price or a maximum-cost guarantee.

Local preparation and verification

python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python -m src.local examples/reviews.json --prepare-only --rights-confirmed --output storage/local-json
python -m src.local examples/reviews.csv --prepare-only --rights-confirmed --output storage/local-csv

The local CLI is preparation-only: it parses, validates, selects, deduplicates and cleans the supplied CSV/JSON so you can inspect the proposed input. It does not call the hosted model or produce the production complaint analysis. Actual analysis runs through the Actor on Apify and requires both rights and AI-processing confirmations. No model download is required for this gateway implementation.

The --prepare-only option is required for local use. Cloud execution pins apify==4.1.0 and uses python -m src. Tests cover malformed exports, optional metadata, privacy, language uncertainty, duplicate handling, caps, budget termination, resume safety and strict gateway-response validation. Actual production complaint analysis runs on Apify through the disclosed gateway; preparation output is not a hosted-model analysis result.

Questions or problems: open an issue on this Actor's Apify Store page with a minimal, anonymized example and the run ID. Do not post raw personal data or API tokens.