{ "openapi": "3.0.1", "info": { "title": "App Store Reviews Scraper API", "description": "Apple App Store reviews scraper API for ASO and product research. Export ratings, titles, review text, dates, app versions and helpful votes across multiple countries; filter before billing, include app metadata. From $0.08 per 1,000 reviews, platform usage included.", "version": "0.1", "x-build-id": "vTrhgU6yeVEWlG1W4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/zenomastro~apple-app-store-reviews-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-zenomastro-apple-app-store-reviews-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/zenomastro~apple-app-store-reviews-pro/runs": { "post": { "operationId": "runs-sync-zenomastro-apple-app-store-reviews-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/zenomastro~apple-app-store-reviews-pro/run-sync": { "post": { "operationId": "run-sync-zenomastro-apple-app-store-reviews-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "apps": { "title": "Apps", "maxItems": 100, "type": "array", "description": "Apps to scrape, as numeric App Store IDs (310633997), apps.apple.com URLs (https://apps.apple.com/us/app/whatsapp-messenger/id310633997) or bundle IDs (net.whatsapp.WhatsApp). Maximum 100 apps. Leave it empty to scrape only the apps found by App name search. Also accepted: appIds, startUrls.", "items": { "type": "string" } }, "searchTerms": { "title": "App name search", "maxItems": 50, "type": "array", "description": "Optional app names or keywords to look up with the iTunes Search API in the first storefront of App Store countries, e.g. [\"WhatsApp\", \"Duolingo\"]. The top matches are added to Apps (100 apps maximum, duplicates removed) and each match is listed as a free search-result row.", "default": [], "items": { "type": "string" } }, "maxAppsPerSearch": { "title": "Apps per search term", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many top matches of each App name search term are scraped, e.g. 1 for just the best match or 3 to include close alternatives. Ranking follows the iTunes Search API, which can differ from the App Store app.", "default": 1 }, "countries": { "title": "App Store countries", "maxItems": 20, "type": "array", "description": "Two-letter storefront codes such as us, gb, it, de, fr, jp (uk is accepted as gb). Reviews, ratings and app availability are per country, so list several storefronts to collect more reviews. Maximum 20 per run; defaults to us. Also accepted: country.", "default": [ "us" ], "items": { "type": "string" } }, "sortBy": { "title": "Sort order", "enum": [ "mostrecent", "mosthelpful" ], "type": "string", "description": "Order of Apple's reviews: mostrecent (newest first, best for monitoring and date windows) or mosthelpful (most helpful first, best for research).", "default": "mostrecent" }, "maxReviewsPerAppCountry": { "title": "Max reviews per app/country", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum reviews kept for each app x storefront, e.g. 200. Apple's RSS feed stops at 500; above 500 the Actor reads the App Store web API, which it pages for as long as Apple returns reviews (up to 5,000). The app-summary row says why an app returned fewer.", "default": 200 }, "maxTotalReviews": { "title": "Maximum total reviews", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Hard cap on billed reviews across the whole run, e.g. 5000. Use it together with the run's maximum charge to control spend. Also accepted: maxItems.", "default": 5000 }, "minRating": { "title": "Minimum stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep reviews with at least this many stars, e.g. 4 for positive reviews only. Filtering happens before billing.", "default": 1 }, "maxRating": { "title": "Maximum stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep reviews with no more than this many stars, e.g. 2 for complaints only. Filtering happens before billing.", "default": 5 }, "hasDeveloperReply": { "title": "Developer reply", "enum": [ "any", "yes", "no" ], "type": "string", "description": "Keep all reviews, only reviews the developer answered, or only unanswered reviews. Developer replies come from the App Store web API, which the Actor then uses for these apps.", "default": "any" }, "minHelpfulVotes": { "title": "Minimum helpful score", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Minimum Apple helpful score (voteSum) a review needs, e.g. 3. Set 0 to disable. Helpful votes exist only in Apple's RSS feed, so with the web API this filter keeps no review. Filtering happens before billing.", "default": 0 }, "containsText": { "title": "Review contains", "type": "string", "description": "Optional case-insensitive text that the review title or body must contain, e.g. crash. Filtering happens before billing.", "default": "" }, "containsAny": { "title": "Review contains any of these keywords", "maxItems": 100, "type": "array", "description": "Keep a review when its title or text mentions at least one of these words or phrases (case-insensitive), e.g. crash, freeze, login. Up to 100.", "default": [], "items": { "type": "string" } }, "containsAll": { "title": "Review contains all of these keywords", "maxItems": 100, "type": "array", "description": "Keep a review only when every one of these words or phrases appears in its title or text (case-insensitive). Up to 100.", "default": [], "items": { "type": "string" } }, "excludeKeywords": { "title": "Exclude reviews with these keywords", "maxItems": 100, "type": "array", "description": "Drop a review when its title or text mentions any of these words or phrases (case-insensitive), e.g. giveaway or promo code. Up to 100.", "default": [], "items": { "type": "string" } }, "reviewedAfter": { "title": "Reviewed after", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$", "type": "string", "description": "Optional start of the date window (inclusive, UTC), as YYYY-MM-DD or an ISO date-time, e.g. 2026-01-01 or 2026-01-01T08:00:00Z. With Most recent order, paging stops once reviews get older than this date.", "default": "" }, "reviewedBefore": { "title": "Reviewed before", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2})?)?$", "type": "string", "description": "Optional end of the date window (inclusive, UTC). A plain date such as 2026-12-31 includes that whole day (up to 23:59:59 UTC); an ISO date-time such as 2026-12-31T12:00:00Z is used as is. Reviews without a readable date are excluded when a date filter is set.", "default": "" }, "reviewedWithinDays": { "title": "Only reviews from the last N days", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Optional rolling date window: keep only reviews posted in the last N days before the run starts, e.g. 7 for a weekly schedule. 0 turns it off. If Reviewed after is also set, the later of the two start dates is used. With Most recent order, paging stops once reviews get older than the window.", "default": 0 }, "includeAppMetadata": { "title": "Include app metadata", "type": "boolean", "description": "Attach app title, developer, category, current version, aggregate rating/count, icon and App Store URL to each review (appMetadata field).", "default": true }, "includeRatingHistogram": { "title": "Include app summary row (rating histogram)", "type": "boolean", "description": "Add one free app-summary row per app x country with the storefront's average rating, total ratings and 1-5 star counts, e.g. {\"1\": 642052, ..., \"5\": 15782454}, how many reviews were returned and why paging stopped, plus the review insights below when they are on.", "default": true }, "includeReviewInsights": { "title": "Include review insights", "type": "boolean", "description": "Add free analytics of the matching reviews to each app-summary row: star distribution and average, developer reply rate (overall and per star) and reply time, monthly trend, app-version trend, top complaint keywords (1-2 stars) and praise keywords (4-5 stars), and keyword mentions. Computed with plain word counting, no AI.", "default": true }, "insightKeywords": { "title": "Insight keywords", "maxItems": 100, "type": "array", "description": "Words or phrases counted in the review insights: how many matching reviews mention each one. Up to 100.", "default": [ "crash", "bug", "support", "price" ], "items": { "type": "string" } }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Optional name for scheduled monitoring, e.g. whatsapp-us-daily. Review IDs returned under this name are remembered between runs and each review gets isNew true/false. Letters, numbers, dot, underscore or hyphen.", "default": "" }, "onlyNew": { "title": "Only new reviews", "type": "boolean", "description": "Return and bill only reviews not returned by earlier runs of the same monitor, e.g. for a daily schedule. Already-seen reviews are skipped for free. Without a Monitor name, one is derived from the apps and countries.", "default": false }, "reviewFeed": { "title": "Review source", "enum": [ "auto", "web", "rss" ], "type": "string", "description": "Where reviews come from. Automatic: Apple's RSS feed (app version and helpful votes, at most 500 reviews per app and country) and the App Store web API (developer replies, deeper paging) when the feed has no reviews, a developer reply filter is set or more than 500 reviews per app/country are requested. Choose one source to force it.", "default": "auto" }, "requestTimeoutSecs": { "title": "Request timeout", "minimum": 5, "maximum": 60, "type": "integer", "description": "Maximum seconds for each Apple HTTP request (Lookup, search, rating and review feed), e.g. 20.", "default": 20 }, "pageRetries": { "title": "Page retries", "minimum": 0, "maximum": 6, "type": "integer", "description": "Retries for timeouts, rate limits (HTTP 429) and Apple server errors, with bounded backoff, e.g. 3. Set 0 to try each request once.", "default": 3 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }