Get an app's daily metric history (rating, ratings count, installs, star histogram, price).

GEThttps://api.appgoat.ai/v1/apps/{app}/history

1+ credits1 + 1 per country refreshed (max 10)MCP tool get_app_historyoperationId getAppHistory

One row per country and day on which a value changed — carry the previous row forward for the days in between. Defaults to the last 90 days. Use it to chart growth or spot rating drops.

Request

curl "https://api.appgoat.ai/v1/apps/com.spotify.music/history" \
  -H "x-api-key: $APPGOAT_API_KEY"

const res = await fetch("https://api.appgoat.ai/v1/apps/com.spotify.music/history", {
  headers: {
    "x-api-key": process.env.APPGOAT_API_KEY,
  },
});
const { data, meta } = await res.json();

import os, requests

res = requests.get(
    "https://api.appgoat.ai/v1/apps/com.spotify.music/history",
    headers={"x-api-key": os.environ["APPGOAT_API_KEY"]}
)
body = res.json()

Path parameters

appstringrequired

Any app identifier: App Store id (284882215, id284882215), Play package (com.spotify.music), Apple bundle id (com.spotify.client), store URL (URL-encoded), apple:<id> / play:<id>, or a name (spotify).

Query parameters

store"apple" | "play"

Disambiguates {app} (a bundle id vs a Play package, or a name).

countrystring

ISO country code(s): us (default), a comma list (paid plans), or all (Studio).

Default "us"

fromstring

Start date (ISO), default 90 days before to.

tostring

End date (ISO), default today.

max_ageinteger

Refresh from the store when our data is older than this many seconds (0 = always). Default 604800 (7 days).

Default 604800

waitboolean

Block up to ~25 s for a refresh (default). false = answer immediately from cache with a job id.

Default true

Response

200 with data: HistoryPoint[]. See the envelope for meta.

countrystring

datestring

ratingnumber | null

ratings_countinteger | null

reviews_countinteger | null

installs_mininteger | null

installs_exactinteger | null

histograminteger[] | null

pricenumber | null

Example

{
  "data": [
    {
      "country": "us",
      "date": "2026-10-22",
      "rating": 4.5,
      "ratings_count": 1,
      "reviews_count": 1,
      "installs_min": 1,
      "installs_exact": 1,
      "histogram": [
        1
      ],
      "price": 4.5
    }
  ],
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9981,
    "request_id": "req_123"
  }
}

Status codes

200

Metric rows, by country then date.

400invalid_param

A parameter is missing or invalid (error.param names it).

401invalid_api_key

Missing or invalid API key.

402insufficient_creditsplan_limit

insufficient_credits (the call costs more than you have left; nothing was done) or plan_limit (a feature of a higher plan).

404app_not_found

Nothing matches {app}, or the store does not have it.

429rate_limited

Too many requests per second for your plan.