Response envelope

Every success is { data, meta }. data is an object or a list; meta carries what the call cost and how fresh the answer is.

{
  "data": { "store": "apple", "app_id": "324684580", "title": "Spotify: Music and Podcasts", … },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9981,
    "request_id": "req_123",
    "store": "apple",
    "freshness": {
      "fetched_at": "2026-10-22T15:03:07Z",
      "age_seconds": 3600,
      "stale": false,
      "refreshing": false,
      "job_id": null
    },
    "next_cursor": null,
    "warnings": []
  }
}

credits_used: what this call cost. credits_remaining: monthly plus pack credits left.
freshness: when the oldest requested country was fetched from the store, whether it is stale, and a job to poll if a refresh is still running. See Freshness.
next_cursor: the next page, or null. See Pagination.
warnings: things worth telling the user (for example that an app was resolved by name).
request_id: quote it when you contact support.

Errors

Errors use the HTTP status and one body shape, whoever answered. Read hint: it says what to do next.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Out of credits: monthly plan credits and credit packs are used up.",
    "hint": "Upgrade your plan, or on Indie / Studio buy a credit pack …",
    "docs": "https://docs.appgoat.ai/errors/insufficient_credits"
  }
}

Every code, from invalid_param to upstream_unavailable, is listed with causes and fixes on Errors.

Getting started

Concepts

Guides

Errors

Errors

​Errors

Errors