Freshness

There is no separate fetch endpoint. App-scoped reads refresh data from the store when ours is older than max_age, and tell you how old it is in meta.freshness.

Parameter	What it does
`max_age`	Seconds. Defaults to 7 days for app data and 1 day for reviews; `0` always refreshes. A refresh costs 1 credit per country fetched (at most 10).
`wait`	`true` (default) blocks up to about 25 seconds for the refresh. On timeout, or with `wait=false`, you get the cached data with `refreshing: true` and a `job_id`. Poll `GET /v1/jobs/{id}` (free) until it is done, then repeat the call.
`country`	`us` by default. Paid plans can pass a comma list (`us,de,jp`); Studio can pass `all`.

An app we have never seen is fetched on the spot. If that takes longer than the wait, the answer is HTTP 202 with data: null and a job_id.

meta.freshness

{
  "fetched_at": "2026-10-22T15:03:07Z",
  "age_seconds": 3600,
  "stale": false,
  "refreshing": false,
  "job_id": null
}

fetched_at is when the oldest requested country was fetched from the store.

Getting started

Concepts

Guides

Errors