{
  "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": "nb9KhrHb1IgxbyAXm"
  },
  "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, up to 100: App Store ids (6448311069), App Store URLs (https://apps.apple.com/us/app/chatgpt/id6448311069), bundle ids (com.burbn.instagram) or app names (searched in each storefront, like searchTerms). Ids, URLs and bundle ids pin one exact app. Cost: $0.002 per app per storefront + $0.0004 per review. Unusable entries get a free notice row. If apps, searchTerms and all chart options are empty, ChatGPT is used as the example.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "App names or keywords to find via App Store search, e.g. \"duolingo\"; up to 20. Each term is searched in every storefront, and each storefront monitors its own top result. If a storefront only shows Apple's stand-in for an app it doesn't sell ('Venmo' in gb returns PayPal), nothing is fetched there and a free notice says so. Each search takes about 3 s (term x storefront). For exact targeting use ids or URLs in Apps.",
            "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 not returned by earlier monitoring runs. The first run returns the newest maxReviewsPerApp reviews and sets the starting point. If a run stops early (maxRecords, max charge, timeout, Apple error), the next run returns what it skipped while Apple still lists it (newest 500). State lives in your key-value store 'app-store-reviews-monitor-state'. Apple updates reviews about daily: 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}