{
  "openapi": "3.0.1",
  "info": {
    "title": "App Store Reviews Scraper | Full History, Dev Replies, $0.50/1K",
    "description": "Full review history of any iOS app in 184 country stores: rating histogram, version numbers, optional developer replies, incremental runs. MCP-ready. Pay per review, no start fee.",
    "version": "0.0",
    "x-build-id": "gIyzI8J2bFq4UA0Kq"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kesar_chen~app-store-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kesar_chen-app-store-reviews-scraper",
        "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/kesar_chen~app-store-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kesar_chen-app-store-reviews-scraper",
        "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/kesar_chen~app-store-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kesar_chen-app-store-reviews-scraper",
        "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",
            "type": "array",
            "description": "One per line: numeric App ID (284882215), App Store URL (https://apps.apple.com/us/app/facebook/id284882215), bundle id (com.facebook.Facebook), or `search:keyword` to take the first search hit.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Two-letter storefront codes (us, gb, jp, de ...), or [\"all\"] for every one of the 184 storefronts (those where the app has no ratings are skipped). Reviews are per storefront; each country is scraped separately.",
            "default": [
              "us"
            ],
            "items": {
              "type": "string"
            }
          },
          "sinceDate": {
            "title": "Only reviews since",
            "type": "string",
            "description": "Absolute date (2026-01-01) or relative (12 months, 30 days). Only applied with sort = recent. Empty = no limit."
          },
          "sort": {
            "title": "Sort",
            "enum": [
              "recent",
              "helpful",
              "favorable",
              "critical"
            ],
            "type": "string",
            "description": "Order in which Apple returns reviews. Use recent for monitoring and date filters.",
            "default": "recent"
          },
          "maxReviewsPerApp": {
            "title": "Max reviews per app per country",
            "minimum": 0,
            "type": "integer",
            "description": "0 = go as deep as Apple's index allows (hundreds of thousands for big apps).",
            "default": 3000
          },
          "summaryWindowMonths": {
            "title": "Summary window (months)",
            "minimum": 0,
            "type": "integer",
            "description": "The summary row counts 1-2 star reviews in the last N months. Percentages are only given when the sample has at least 20 reviews. 0 = off.",
            "default": 12
          },
          "incremental": {
            "title": "Incremental (only new reviews since last run)",
            "type": "boolean",
            "description": "Remembers which reviews it has seen per app and country in a named key-value store, and outputs only new ones on later runs. Requires sort = recent.",
            "default": false
          },
          "stateStoreName": {
            "title": "State store name",
            "type": "string",
            "description": "Named key-value store that keeps the incremental state. Named stores never expire.",
            "default": "appstore-reviews-state"
          },
          "minRating": {
            "title": "Min rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep only reviews with at least this many stars. Filtered-out reviews are not written and not charged. With sort = favorable the run stops early once ratings fall below this.",
            "default": 1
          },
          "maxRating": {
            "title": "Max rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep only reviews with at most this many stars. 1-2 for complaint monitoring. With sort = critical the run stops early once ratings rise above this.",
            "default": 5
          },
          "untilDate": {
            "title": "Only reviews until",
            "type": "string",
            "description": "Upper bound on the review date, same formats as 'Only reviews since' (2026-03-01, 30 days). Combine both to pick a window, for example the two weeks after a release."
          },
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Keep only reviews whose title or text contains at least one of these words, case-insensitive. Empty = no filter.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "developerResponseFilter": {
            "title": "Developer response filter",
            "enum": [
              "all",
              "with",
              "without"
            ],
            "type": "string",
            "description": "Needs 'Include developer responses' on. Every review is still looked up (and charged as a check); only the matching ones are written.",
            "default": "all"
          },
          "searchResultsPerKeyword": {
            "title": "Apps per search keyword",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "How many apps a 'search:keyword' entry in Apps expands to, ordered by App Store relevance.",
            "default": 1
          },
          "includeDeveloperResponses": {
            "title": "Include developer responses",
            "type": "boolean",
            "description": "Look up the developer reply for each review of this run and attach it. Slow: expect roughly 1,000 reviews per 5 to 15 minutes per app and country. Charged per review checked (same price as a review), not per reply found. Narrow the scope with sinceDate, maxReviewsPerApp or incremental mode.",
            "default": false
          },
          "maxDeveloperResponseChecks": {
            "title": "Max reviews to check for developer responses",
            "minimum": 0,
            "type": "integer",
            "description": "Per app per country, only with includeDeveloperResponses. Caps how deep the reply lookup goes; the rest of the run is unaffected. 0 = no cap.",
            "default": 1000
          },
          "notifyWebhookUrl": {
            "title": "Notify: webhook URL",
            "type": "string",
            "description": "Paste a Slack incoming webhook, a Discord channel webhook, a Feishu/Lark custom bot webhook, or any HTTPS endpoint. After each app × country the Actor posts the reviews written in this run that are at or below the rating threshold. With incremental mode on, that means only new low-rated reviews. Unknown hosts receive a JSON body."
          },
          "notifyMaxRating": {
            "title": "Notify: max rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only reviews with this many stars or fewer are posted. 5 = post everything written.",
            "default": 2
          },
          "notifyMaxItems": {
            "title": "Notify: max reviews per message",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "The rest are summarised as a count; all of them are in the dataset.",
            "default": 10
          },
          "notifyEvenIfEmpty": {
            "title": "Notify: post even when nothing matched",
            "type": "boolean",
            "description": "Off = silence when there is nothing at or below the threshold.",
            "default": false
          },
          "includeReviewerName": {
            "title": "Include reviewer name and profile URL",
            "type": "boolean",
            "description": "Off by default to keep personal data out of your dataset.",
            "default": false
          },
          "pageSize": {
            "title": "Page size",
            "minimum": 250,
            "maximum": 3000,
            "type": "integer",
            "description": "Advanced tuning. Leave the default unless support asks you to change it.",
            "default": 3000
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "scrape",
              "probe",
              "canary"
            ],
            "type": "string",
            "description": "Leave on scrape.",
            "default": "scrape"
          },
          "requests": {
            "title": "Probe: requests",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Probe only.",
            "default": 60
          },
          "concurrency": {
            "title": "Probe: concurrency",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Probe only.",
            "default": 1
          },
          "cacheBust": {
            "title": "Probe: cache-busting nonce",
            "type": "boolean",
            "description": "Probe only.",
            "default": false
          },
          "startOffset": {
            "title": "Probe: start offset",
            "minimum": 0,
            "type": "integer",
            "description": "Probe only.",
            "default": 0
          },
          "testRss": {
            "title": "Probe: also hit RSS",
            "type": "boolean",
            "description": "Probe only.",
            "default": true
          },
          "testProxy": {
            "title": "Probe: also hit same-origin proxy",
            "type": "boolean",
            "description": "Probe only.",
            "default": true
          },
          "appId": {
            "title": "Probe: app id",
            "type": "string",
            "description": "Probe only.",
            "default": "284882215"
          },
          "storefront": {
            "title": "Probe: X-Apple-Store-Front",
            "type": "string",
            "description": "Probe only.",
            "default": "143441-1,29"
          },
          "country": {
            "title": "Probe: country",
            "type": "string",
            "description": "Probe only.",
            "default": "us"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}