{
  "openapi": "3.0.1",
  "info": {
    "title": "App Store Reviews Scraper | Ratings Across All Countries",
    "description": "Collect Apple App Store reviews and ratings for any app across 150+ country storefronts. Get rating, title, body, author, date, app version, and country in clean JSON. Search by app name or paste app URLs; optional app metadata enrichment.",
    "version": "1.0",
    "x-build-id": "WPyTYEjhHiP1kJRnL"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~app-store-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-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/abotapi~app-store-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-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/abotapi~app-store-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-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",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "url"
            ],
            "type": "string",
            "description": "How to select apps. 'search' resolves app names to apps via the App Store; 'url' takes App Store app links directly.",
            "default": "search"
          },
          "queries": {
            "title": "App name searches",
            "type": "array",
            "description": "App names or keywords to look up (for example 'Instagram', 'Spotify'). Each term resolves to the top matching app(s) and its reviews are collected. Ignored in URL mode.",
            "items": {
              "type": "string"
            }
          },
          "appsPerQuery": {
            "title": "Apps per search term",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many top matching apps to take for each search term. Use 1 for the single best match. Ignored in URL mode.",
            "default": 1
          },
          "urls": {
            "title": "App Store URLs",
            "type": "array",
            "description": "App Store app links, for example https://apps.apple.com/us/app/instagram/id389801252 . Multiple URLs supported. The app id is read from the /id{digits} part; the storefront in the link is used only if you leave Countries empty.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "ISO 2-letter storefront codes to collect reviews from (for example us, gb, de, jp). Each country is a separate review stream. Leave empty to use the storefront from each URL (URL mode) or 'us' (search mode). Use 'all' to sweep a broad built-in set of major storefronts.",
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "Sort reviews by",
            "enum": [
              "mostRecent",
              "mostHelpful"
            ],
            "type": "string",
            "description": "Order reviews are returned in per country.",
            "default": "mostRecent"
          },
          "minRating": {
            "title": "Minimum rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep only reviews with at least this star rating (1 to 5). Leave empty for all."
          },
          "maxRating": {
            "title": "Maximum rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep only reviews with at most this star rating (1 to 5). Leave empty for all."
          },
          "fetchDetails": {
            "title": "Enrich with app details",
            "type": "boolean",
            "description": "Also attach app metadata (developer, average rating, rating count, genre, icon, price, release notes) to each review. Adds an extra lookup per app.",
            "default": false
          },
          "maxItems": {
            "title": "Max reviews",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of reviews to collect in total. 0 means no limit (stops at Max pages per country across all countries). Predictable, keeps the first run cheap.",
            "default": 20
          },
          "maxPages": {
            "title": "Max pages per country",
            "minimum": 0,
            "type": "integer",
            "description": "Optional bound on review pages walked per country (50 reviews per page). Leave empty to walk every review page; the storefront naturally stops paginating once it runs out. The run also stops at Max reviews."
          },
          "resumeFromRunId": {
            "title": "Resume from run ID",
            "type": "string",
            "description": "Optional: paste a previous run ID (or dataset ID) from this actor. Reviews already collected there are skipped, so this run only returns new ones. For repeated scheduled monitoring of the SAME search, use Incremental mode below instead. Leave empty for a normal run."
          },
          "incrementalMode": {
            "title": "Incremental mode (recurring updates)",
            "type": "boolean",
            "description": "For a search you run on a schedule: remember the reviews already seen and return only what changed (NEW/UPDATED/REAPPEARED, plus EXPIRED if enabled) instead of pasting a Resume from run ID every time. Off by default so a first-time run behaves exactly as before.",
            "default": false
          },
          "stateKey": {
            "title": "State key (incremental mode)",
            "type": "string",
            "description": "Optional: name this monitoring campaign so you can run several tracked searches independently. Leave empty to derive the state automatically from your search settings (mode, queries/URLs, countries, sort, rating filters, enrichment) — two different filter setups never share a baseline. Ignored when Incremental mode is off."
          },
          "emitUnchanged": {
            "title": "Emit unchanged reviews (incremental mode)",
            "type": "boolean",
            "description": "Also return reviews that have not changed since the last run (changeType = UNCHANGED). Off by default so a recurring run returns only what changed — turning this on returns and bills for every scanned review, every run. Ignored when Incremental mode is off.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit expired reviews (incremental mode)",
            "type": "boolean",
            "description": "Also return a row for each previously-tracked review that no longer appears (changeType = EXPIRED) once a run completes a full, uncapped scan. Off by default — turning this on returns and bills an extra row per review that disappeared. An EXPIRED row carries only the review id and timestamps, not its original text (kept out of the saved state to keep it small). Ignored when Incremental mode is off.",
            "default": false
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Connection settings. The default works on any Apify plan.",
            "default": {
              "useApifyProxy": true
            }
          },
          "mcpConnectors": {
            "title": "Pipe results into your apps (optional)",
            "type": "array",
            "description": "Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write. Leave empty to skip; never changes the dataset output. Supported: Notion, Linear, Airtable, Apify."
          },
          "notionParentPageUrl": {
            "title": "Notion parent page (Notion connector only)",
            "type": "string",
            "description": "URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors."
          },
          "maxNotifyListings": {
            "title": "Max items to export per connector",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Cap on items written to each connector per run. Does not affect the dataset.",
            "default": 50
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}