{
  "openapi": "3.0.1",
  "info": {
    "title": "App Store Reviews & Charts Monitor",
    "description": "Apple App Store reviews, app metadata and top-chart ranks by app id, URL or search term, across storefronts, with new-since-last-run review tracking. Official public Apple endpoints only.",
    "version": "0.1",
    "x-build-id": "iqBELKiNqlliydhlB"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/bigdavidson~app-store-reviews-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-bigdavidson-app-store-reviews-monitor",
        "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/bigdavidson~app-store-reviews-monitor/runs": {
      "post": {
        "operationId": "runs-sync-bigdavidson-app-store-reviews-monitor",
        "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/bigdavidson~app-store-reviews-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-bigdavidson-app-store-reviews-monitor",
        "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": "Apps to monitor: numeric App Store ids (6448311069), App Store URLs (https://apps.apple.com/us/app/chatgpt/id6448311069), bundle ids (com.burbn.instagram) or plain app names (searched for, like searchTerms). Up to 100. Ids, URLs and bundle ids mean one exact app in every storefront; an app name is searched in each storefront separately. Each app costs $0.002 per storefront (metadata) plus $0.0004 per review. If apps, searchTerms and every chart option are left empty, the example app ChatGPT is used. Entries that cannot be used are skipped with a free notice row; if none is usable, nothing is fetched or charged.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Optional app names/keywords to find via the App Store search (e.g. \"duolingo\"). Up to 20. Each term is searched in every storefront, and each storefront monitors its own top result(s). Where a storefront's top result is only Apple's stand-in for an app it does not sell (the term is in the top result's name in other storefronts but not there, e.g. 'Venmo' in gb returns PayPal), nothing is fetched there and a free notice says so. Searching takes about 3 s per term per storefront (Apple allows ~20 searches a minute); past 200 searches the remaining storefronts reuse the app found. Use ids or URLs for exact targeting.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Storefronts (countries)",
            "type": "array",
            "description": "2-letter App Store country codes (us, gb, de, jp, br…) or country names. Reviews, prices and charts are per storefront. Default: us (or the country in an App Store URL). Max 50.",
            "items": {
              "type": "string"
            }
          },
          "modes": {
            "title": "What to fetch",
            "type": "array",
            "description": "Any of: metadata (app details + rating, $0.002/app/storefront), reviews (recent customer reviews, $0.0004 each), charts (top-chart ranks, $0.0005/row), or all. Case-insensitive; synonyms such as details, ratings or rankings work. Empty = metadata + reviews, or charts only when a chart option (chartTypes, chartGenres, chartTrackedAppsOnly) is set. When both modes and a chart option are set, charts is added to these modes.",
            "items": {
              "type": "string"
            }
          },
          "maxReviewsPerApp": {
            "title": "Max reviews per app per storefront",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Cap on reviews returned per app per storefront, newest first. Apple's public feed exposes at most the 500 most recent written reviews per storefront.",
            "default": 100
          },
          "onlyNewReviews": {
            "title": "Only reviews new since the last run",
            "type": "boolean",
            "description": "Monitoring mode: return (and charge for) only reviews that earlier monitoring runs did not return. The first monitoring run returns the newest maxReviewsPerApp reviews and sets where the monitor starts: older reviews are never returned by it. If a run stops before returning everything it should (maxRecords, max charge, timeout, an Apple error, or on later runs maxReviewsPerApp), the next run returns the reviews it skipped, while Apple still lists them (newest 500). Seen review ids are saved in the named key-value store 'app-store-reviews-monitor-state' in your account, per app, storefront and stateKey. Apple's review feed updates about once a day, so schedule at most daily.",
            "default": false
          },
          "ratings": {
            "title": "Star filter",
            "type": "array",
            "description": "Optional: only return reviews with these star ratings, e.g. [\"1\", \"2\"], [\"negative\"] (1-2), [\"positive\"] (4-5) or ranges like [\"1-3\"]. Empty = all ratings. Filtered-out reviews are not charged. The app record's review aggregates (reviews_scanned, histogram, version_ratings) still cover every review scanned, not only the ones returned.",
            "items": {
              "type": "string"
            }
          },
          "chartTypes": {
            "title": "Charts",
            "type": "array",
            "description": "Top charts: top-free, top-paid, top-free-ipad, top-paid-ipad (the App Store's Apps charts, games excluded; for game charts add chartGenres \"Games\", or write e.g. \"top free games\"), top-grossing, top-grossing-ipad (apps and games combined; no longer shown in the App Store), top-free-mac. Setting this turns on charts. Default when only other chart options are set: top-free. $0.0005 per row. Unrecognised names are skipped with a free notice; none is substituted.",
            "items": {
              "type": "string"
            }
          },
          "chartGenres": {
            "title": "Chart genres",
            "type": "array",
            "description": "Optional App Store genres for the charts: names (Games, Productivity, Finance, Puzzle games…) or ids (6014). Empty = the overall chart. Setting this turns on charts. Unknown genres are skipped with a free notice; if none is usable, no chart is fetched.",
            "items": {
              "type": "string"
            }
          },
          "chartLimit": {
            "title": "Chart depth",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Rows per chart (1-100). Each row costs $0.0005. Some Apps charts have fewer positions: the iPad Apps charts (about 30-70), and top-paid (about 20-60) when Apple's newer chart feed does not answer (a free notice row says so).",
            "default": 25
          },
          "chartTrackedAppsOnly": {
            "title": "Charts: only my apps' ranks",
            "type": "boolean",
            "description": "Rank tracking: scan up to 100 positions of each chart and return only rows for the apps in 'apps'/'searchTerms' — one row per app per chart per storefront, with rank null when the app is not within chart_depth positions. Turns on charts; without modes set, only charts are fetched (no metadata or review charges). Needs apps or searchTerms: without any usable one, no chart is fetched or charged.",
            "default": false
          },
          "searchResultsPerTerm": {
            "title": "Apps per search term",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many top search results to monitor per search term.",
            "default": 1
          },
          "maxRecords": {
            "title": "Max charged records",
            "minimum": 1,
            "type": "integer",
            "description": "Optional hard cap on charged records (app records + reviews + chart rows) for this run. Free notice rows do not count."
          },
          "stateKey": {
            "title": "Monitor name",
            "type": "string",
            "description": "Name of a monitor: keeps separate new-review state for separate monitors of the same app (e.g. one per Slack channel or star filter). Runs with a stateKey or onlyNewReviews save state; other runs only read it. Default: default."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}