# Get Apple chart history

Read dated rank points for one numeric store ID on a stored Apple chart series.

## Contract status

Preview contract: these routes and tools are implemented in the shared contract, but the public host, customer API access and OAuth flow have not been deployment verified.

## Endpoint: GET /v1/charts/apps/{storeId}/history

- Method: `GET`
- Path: `/v1/charts/apps/{storeId}/history`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_apple_chart_history`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `storeId` | path | numeric string | yes | Apple App Store identifier. |
| `country` | query | ^[a-z]{2}$ | no | Apple storefront. Defaults to us. Coverage is us, gb, fr, de, br, be. |
| `categoryId` | query | all or digits | no | Overall (all) or an Apple category id. Defaults to all. |
| `chartType` | query | free | paid | grossing | no | Apple chart type. Defaults to free. Grossing is a position, not dollars. |
| `limit` | query | integer, 1–100 | no | History length. Defaults to 30. There is no view filter. |

## Known errors

- 400 invalid_request for an invalid filter, identity or limit.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing scope or unavailable preview access.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.

## Request

Path storeId is numeric. Query accepts country, categoryId, chartType and limit. There is no view parameter. This GET never calls Apple.

```
curl --get 'https://api.peekpanda.com/v1/charts/apps/0000000000/history' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'country=us' \
  --data-urlencode 'categoryId=all' \
  --data-urlencode 'chartType=free' \
  --data-urlencode 'limit=30'
```

## Response

Matches appleChartHistorySchema: { storeId, query, history:[{day, rank}], app:{...}|null, countries:[{country, day, rank, depth}] }. The example uses store ID 0000000000.

```
{
  "storeId": "0000000000",
  "query": {
    "country": "us",
    "categoryId": "all",
    "chartType": "free",
    "limit": 30
  },
  "history": [
    {
      "day": "2026-09-05",
      "rank": 2
    },
    {
      "day": "2026-09-06",
      "rank": 1
    }
  ],
  "app": {
    "storeId": "0000000000",
    "name": "Example Calorie Tracker",
    "iconUrl": "https://example.com/icon.png",
    "developer": "Example Labs",
    "categoryName": "Health & Fitness"
  },
  "countries": [
    {
      "country": "us",
      "day": "2026-09-06",
      "rank": 1,
      "depth": 100
    }
  ]
}

```

## Source

The same stored Apple ranking RSS / modern RSS snapshots as GET /v1/charts. Grossing remains a position. Chart GET never calls Apple.

## Refresh

History is assembled from published daily snapshots. peekpanda-apple-charts-refresh only fills unfinished UTC-day lists; it does not rewrite completed history.