# Get market leaderboard

Read the complete bounded market page in one request: three overall charts, the selected chart, market overview, and signals for the apps shown.

## Endpoint: GET /v1/market/leaderboard

- Method: `GET`
- Path: `/v1/market/leaderboard`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_market`
- MCP action: `leaderboard`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | ^[a-z]{2}$ | no | Apple storefront as two lowercase letters. Defaults to us. |
| `categoryId` | query | all or digits | no | Overall or the Apple category for the selected chart. Defaults to all. |
| `chartType` | query | free | paid | grossing | no | Selected chart type. Defaults to free. |

## Known errors

- 400 invalid_request for an unknown query parameter, invalid storefront, category or chart type.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing context:read scope or unavailable preview access.
- 429 rate_limited; wait for the Retry-After seconds, then send the same request again.

## Request

Send country, categoryId and chartType as query parameters. This GET reads stored evidence and never starts collection.

```
curl --get 'https://api.peekpanda.com/v1/market/leaderboard' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'country=us' \
  --data-urlencode 'categoryId=6013' \
  --data-urlencode 'chartType=paid'
```

## MCP request

Call get_market with action leaderboard. Path fields go in params, filters in query, and a write body in body.

```
{
  "name": "get_market",
  "arguments": {
    "request": {
      "action": "leaderboard"
    }
  }
}

```

## Response

The response keeps the full chart-page fields, including history, coverage and freshness, for free, paid, grossing and a category-selected chart. For categoryId=all, viewChart is null because charts[chartType] is the selected chart already. It also includes the market overview and one signals batch for every app rendered. Each chart has at most 100 rows, so the response has at most 400 chart rows before duplicates; signals remain capped at 600 unique apps.

```
{
  "projection": {
    "computedAt": "2026-09-16T12:00:00.000Z",
    "staleAt": "2026-09-16T15:00:00.000Z",
    "stale": false
  },
  "overview": {
    "country": "us",
    "chart": {
      "day": "2026-09-10",
      "previousDay": "2026-09-09",
      "historyDays": 6
    },
    "weeks": [
      "2026-07-20",
      "2026-07-27",
      "2026-08-03",
      "2026-08-10",
      "2026-08-17",
      "2026-08-24",
      "2026-08-31",
      "2026-09-07"
    ],
    "pulse": {
      "paid": {
        "totalAds": 905,
        "liveAds": 830,
        "advertisers": 61,
        "startedLast7Days": 122,
        "longestDaysLive": 332,
        "weeklyStarts": [
          26,
          55,
          73,
          38,
          72,
          118,
          126,
          67
        ],
        "weeklyAdvertisers": [
          2,
          3,
          5,
          1,
          2,
          7,
          3,
          1
        ]
      },
      "organic": {
        "posts": 4879,
        "matchedPosts": 1397,
        "matchedApps": 699,
        "weeklyFound": [
          0,
          4,
          1,
          106,
          156,
          98,
          103,
          51
        ],
        "viewsCountedAt": "2026-05-29T00:00:00.000Z"
      },
      "keywords": {
        "rankedKeywords": 2285,
        "popularityTerms": 33039,
        "storefronts": 10
      }
    },
    "boards": {
      "advertisers": [
        {
          "storeId": "6480417616",
          "name": "Cal AI - Calorie Tracker",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/a1/74/2f/a1742f0e-6092-1e6c-38a9-135fd674f189/AppIcon-0-0-1x_U007ephone-0-1-85-220.png/128x128bb.png",
          "categoryName": "Health & Fitness",
          "liveAds": 95,
          "totalAds": 95,
          "startedLast7Days": 30,
          "medianDaysLive": 23,
          "longestDaysLive": 149,
          "videoShare": 0.905,
          "topCallToAction": "Learn more",
          "placement": {
            "rank": 6,
            "previousRank": 7,
            "chartType": "free",
            "categoryId": "6013",
            "categoryName": "Health & Fitness",
            "day": "2026-09-10"
          }
        }
      ],
      "viral": [
        {
          "storeId": "6759000863",
          "name": "Cheater Buster : AI Checker",
          "iconUrl": null,
          "categoryName": "Utilities",
          "matchedPosts": 6,
          "views": 275617771,
          "medianViews": 41073742,
          "bestPostViews": 82900000,
          "placement": null
        },
        {
          "storeId": "529479190",
          "name": "Clash of Clans",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/d7/af/ca/d7afca1f-0b51-4cc1-7e7f-b0fba87e3739/AppIcon-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png",
          "categoryName": "Games",
          "matchedPosts": 1,
          "views": 146800000,
          "medianViews": 146800000,
          "bestPostViews": 146800000,
          "placement": {
            "rank": 25,
            "previousRank": 33,
            "chartType": "grossing",
            "categoryId": "6014",
            "categoryName": "Games",
            "day": "2026-09-10"
          }
        }
      ],
      "searchOwners": [
        {
          "storeId": "389801252",
          "name": "Instagram",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/5a/18/99/5a189914-fa88-fab3-7ce2-506a624d2fbf/Prod-0-0-1x_U007epad-0-1-0-sRGB-85-220.png/128x128bb.png",
          "categoryName": "Photo & Video",
          "ranked": 328,
          "top10": 197,
          "top3": 86,
          "placement": {
            "rank": 2,
            "previousRank": 2,
            "chartType": "free",
            "categoryId": "6008",
            "categoryName": "Photo & Video",
            "day": "2026-09-10"
          }
        }
      ]
    },
    "searches": {
      "hottest": [
        {
          "query": "instagram",
          "popularity": 100,
          "previousPopularity": 100,
          "difficulty": 100,
          "rankingApps": 148,
          "leader": {
            "storeId": "389801252",
            "name": "Instagram",
            "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/5a/18/99/5a189914-fa88-fab3-7ce2-506a624d2fbf/Prod-0-0-1x_U007epad-0-1-0-sRGB-85-220.png/128x128bb.png"
          }
        }
      ],
      "wideOpen": [
        {
          "query": "empower",
          "popularity": 69,
          "difficulty": 0,
          "opportunity": 69,
          "rankingApps": 184,
          "leader": {
            "storeId": "1454849875",
            "name": "Empower - Your ride, your way",
            "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/02/f6/b9/02f6b9f2-104b-e30c-5b04-2e004077a347/AppIconPassenger-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png"
          }
        }
      ]
    },
    "findings": {
      "climbingAndBuying": [
        {
          "storeId": "6480417616",
          "name": "Cal AI - Calorie Tracker",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/a1/74/2f/a1742f0e-6092-1e6c-38a9-135fd674f189/AppIcon-0-0-1x_U007ephone-0-1-85-220.png/128x128bb.png",
          "categoryName": "Health & Fitness",
          "placement": {
            "rank": 6,
            "previousRank": 7,
            "chartType": "free",
            "categoryId": "6013",
            "categoryName": "Health & Fitness",
            "day": "2026-09-10"
          },
          "startedLast7Days": 30,
          "liveAds": 95
        }
      ],
      "topTenUncollected": [
        {
          "storeId": "555376968",
          "name": "ESPN Fantasy Sports & More",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/fc/c8/f1/fcc8f1f5-9a4d-1a40-59e7-fae3fc7db2c8/AppIcon-0-0-1x_U007epad-0-11-0-85-220.png/128x128bb.png",
          "categoryName": "Sports",
          "rank": 2,
          "chartType": "free"
        }
      ],
      "newEntrants": [
        {
          "storeId": "6760173601",
          "name": "Muse from Meta",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/bf/06/f7/bf06f70f-8230-7065-5096-3d89145e18cf/HatchAppIconPublic-0-0-1x_U007ephone-0-1-0-sRGB-0-85-220.png/128x128bb.png",
          "categoryName": "Productivity",
          "rank": 4,
          "hasAds": false,
          "hasOrganic": false,
          "hasKeywords": false
        }
      ],
      "viralNotBuying": [
        {
          "storeId": "6759000863",
          "name": "Cheater Buster : AI Checker",
          "iconUrl": null,
          "categoryName": "Utilities",
          "matchedPosts": 6,
          "views": 275617771
        }
      ],
      "buyingNotCharting": [
        {
          "storeId": "1018368216",
          "name": "Cantina: AI Video & Characters",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/2a/78/80/2a78801f-f10f-78d8-d99d-9701b44edfa2/AppIcon-0-0-1x_U007ephone-0-1-0-sRGB-85-220.png/128x128bb.png",
          "categoryName": "Photo & Video",
          "liveAds": 30,
          "placement": {
            "rank": 13,
            "previousRank": 10,
            "chartType": "free",
            "categoryId": "6008",
            "categoryName": "Photo & Video",
            "day": "2026-09-10"
          }
        }
      ]
    },
    "suspects": [
      {
        "storeId": "341232718",
        "name": "MyFitnessPal: Calorie Counter",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/3b/97/aa/3b97aa91-aa9d-d66d-e531-8cdef051e137/AppIcon-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png",
        "categoryName": "Health & Fitness",
        "boards": [
          "chart",
          "paid",
          "organic",
          "search"
        ],
        "placement": {
          "rank": 1,
          "previousRank": 1,
          "chartType": "grossing",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "day": "2026-09-10"
        },
        "paid": {
          "liveAds": 19,
          "startedLast7Days": 2
        },
        "organic": {
          "matchedPosts": 1,
          "views": 342500
        },
        "keywords": {
          "top10": 45
        }
      }
    ]
  },
  "charts": {
    "free": {
      "query": {
        "country": "us",
        "categoryId": "all",
        "chartType": "free",
        "view": "rankings",
        "limit": 100
      },
      "coverage": {
        "countries": [
          {
            "code": "us",
            "name": "United States"
          },
          {
            "code": "gb",
            "name": "United Kingdom"
          },
          {
            "code": "fr",
            "name": "France"
          },
          {
            "code": "de",
            "name": "Germany"
          },
          {
            "code": "br",
            "name": "Brazil"
          },
          {
            "code": "be",
            "name": "Belgium"
          },
          {
            "code": "jp",
            "name": "Japan"
          },
          {
            "code": "kr",
            "name": "South Korea"
          },
          {
            "code": "cn",
            "name": "China"
          },
          {
            "code": "ru",
            "name": "Russia"
          }
        ],
        "categories": [
          {
            "id": "all",
            "name": "Overall"
          }
        ],
        "chartTypes": [
          "free",
          "paid",
          "grossing"
        ]
      },
      "snapshot": {
        "id": "chart-snapshot-example",
        "day": "2026-09-06",
        "sourceUpdatedAt": "2026-09-06T00:00:00.000Z",
        "fetchedAt": "2026-09-06T00:15:00.000Z",
        "depth": 100,
        "previousDay": "2026-09-05",
        "stale": false
      },
      "summary": {
        "trackedApps": 1,
        "rankedApps": 1,
        "gainers": 0,
        "losers": 0,
        "newEntrants": 0,
        "newReleases": 0
      },
      "insights": {
        "categoryMix": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "count": 1
          }
        ],
        "releaseAges": [
          {
            "label": "1-3years",
            "count": 1
          }
        ],
        "categoryLeaders": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "storeId": "0000000000",
            "appName": "Example Calorie Tracker",
            "iconUrl": "https://example.com/icon.png",
            "day": "2026-09-06",
            "depth": 100
          }
        ],
        "storefronts": [
          {
            "country": "us",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "gb",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "fr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "de",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "br",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "be",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "jp",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "kr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "cn",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "ru",
            "day": "2026-09-06",
            "depth": 100
          }
        ]
      },
      "data": [
        {
          "storeId": "0000000000",
          "name": "Example Calorie Tracker",
          "developer": "Example Labs",
          "iconUrl": "https://example.com/icon.png",
          "appUrl": "https://apps.apple.com/us/app/id0000000000",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "releaseDate": "2024-05-01",
          "price": 0,
          "currency": "USD",
          "rating": 4.7,
          "ratingCount": 12450,
          "metadataUpdatedAt": "2026-09-06T00:15:00.000Z",
          "history": [
            {
              "day": "2026-09-06",
              "rank": 1
            }
          ],
          "rank": 1,
          "previousRank": 2,
          "movement": 1,
          "status": "ranked",
          "inCatalogue": true,
          "estimates": {
            "monthlyInstalls": {
              "kind": "range",
              "scope": "worldwide",
              "range": {
                "low": 40000,
                "mid": 84000,
                "high": 170000
              },
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": {
                "kind": "range",
                "scope": "worldwide",
                "range": {
                  "low": 34000,
                  "mid": 72000,
                  "high": 150000
                },
                "observedAt": "2026-09-05T00:00:00.000Z"
              }
            },
            "monthlyRevenue": {
              "kind": "below_floor",
              "scope": "worldwide",
              "ceiling": 5000,
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": null
            },
            "currency": "USD"
          }
        }
      ],
      "updatedAt": "2026-09-06T00:15:00.000Z"
    },
    "paid": {
      "query": {
        "country": "us",
        "categoryId": "all",
        "chartType": "paid",
        "view": "rankings",
        "limit": 100
      },
      "coverage": {
        "countries": [
          {
            "code": "us",
            "name": "United States"
          },
          {
            "code": "gb",
            "name": "United Kingdom"
          },
          {
            "code": "fr",
            "name": "France"
          },
          {
            "code": "de",
            "name": "Germany"
          },
          {
            "code": "br",
            "name": "Brazil"
          },
          {
            "code": "be",
            "name": "Belgium"
          },
          {
            "code": "jp",
            "name": "Japan"
          },
          {
            "code": "kr",
            "name": "South Korea"
          },
          {
            "code": "cn",
            "name": "China"
          },
          {
            "code": "ru",
            "name": "Russia"
          }
        ],
        "categories": [
          {
            "id": "all",
            "name": "Overall"
          }
        ],
        "chartTypes": [
          "free",
          "paid",
          "grossing"
        ]
      },
      "snapshot": {
        "id": "chart-snapshot-example",
        "day": "2026-09-06",
        "sourceUpdatedAt": "2026-09-06T00:00:00.000Z",
        "fetchedAt": "2026-09-06T00:15:00.000Z",
        "depth": 100,
        "previousDay": "2026-09-05",
        "stale": false
      },
      "summary": {
        "trackedApps": 1,
        "rankedApps": 1,
        "gainers": 0,
        "losers": 0,
        "newEntrants": 0,
        "newReleases": 0
      },
      "insights": {
        "categoryMix": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "count": 1
          }
        ],
        "releaseAges": [
          {
            "label": "1-3years",
            "count": 1
          }
        ],
        "categoryLeaders": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "storeId": "0000000000",
            "appName": "Example Calorie Tracker",
            "iconUrl": "https://example.com/icon.png",
            "day": "2026-09-06",
            "depth": 100
          }
        ],
        "storefronts": [
          {
            "country": "us",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "gb",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "fr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "de",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "br",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "be",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "jp",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "kr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "cn",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "ru",
            "day": "2026-09-06",
            "depth": 100
          }
        ]
      },
      "data": [
        {
          "storeId": "0000000000",
          "name": "Example Calorie Tracker",
          "developer": "Example Labs",
          "iconUrl": "https://example.com/icon.png",
          "appUrl": "https://apps.apple.com/us/app/id0000000000",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "releaseDate": "2024-05-01",
          "price": 0,
          "currency": "USD",
          "rating": 4.7,
          "ratingCount": 12450,
          "metadataUpdatedAt": "2026-09-06T00:15:00.000Z",
          "history": [
            {
              "day": "2026-09-06",
              "rank": 1
            }
          ],
          "rank": 1,
          "previousRank": 2,
          "movement": 1,
          "status": "ranked",
          "inCatalogue": true,
          "estimates": {
            "monthlyInstalls": {
              "kind": "range",
              "scope": "worldwide",
              "range": {
                "low": 40000,
                "mid": 84000,
                "high": 170000
              },
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": {
                "kind": "range",
                "scope": "worldwide",
                "range": {
                  "low": 34000,
                  "mid": 72000,
                  "high": 150000
                },
                "observedAt": "2026-09-05T00:00:00.000Z"
              }
            },
            "monthlyRevenue": {
              "kind": "below_floor",
              "scope": "worldwide",
              "ceiling": 5000,
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": null
            },
            "currency": "USD"
          }
        }
      ],
      "updatedAt": "2026-09-06T00:15:00.000Z"
    },
    "grossing": {
      "query": {
        "country": "us",
        "categoryId": "all",
        "chartType": "grossing",
        "view": "rankings",
        "limit": 100
      },
      "coverage": {
        "countries": [
          {
            "code": "us",
            "name": "United States"
          },
          {
            "code": "gb",
            "name": "United Kingdom"
          },
          {
            "code": "fr",
            "name": "France"
          },
          {
            "code": "de",
            "name": "Germany"
          },
          {
            "code": "br",
            "name": "Brazil"
          },
          {
            "code": "be",
            "name": "Belgium"
          },
          {
            "code": "jp",
            "name": "Japan"
          },
          {
            "code": "kr",
            "name": "South Korea"
          },
          {
            "code": "cn",
            "name": "China"
          },
          {
            "code": "ru",
            "name": "Russia"
          }
        ],
        "categories": [
          {
            "id": "all",
            "name": "Overall"
          }
        ],
        "chartTypes": [
          "free",
          "paid",
          "grossing"
        ]
      },
      "snapshot": {
        "id": "chart-snapshot-example",
        "day": "2026-09-06",
        "sourceUpdatedAt": "2026-09-06T00:00:00.000Z",
        "fetchedAt": "2026-09-06T00:15:00.000Z",
        "depth": 100,
        "previousDay": "2026-09-05",
        "stale": false
      },
      "summary": {
        "trackedApps": 1,
        "rankedApps": 1,
        "gainers": 0,
        "losers": 0,
        "newEntrants": 0,
        "newReleases": 0
      },
      "insights": {
        "categoryMix": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "count": 1
          }
        ],
        "releaseAges": [
          {
            "label": "1-3years",
            "count": 1
          }
        ],
        "categoryLeaders": [
          {
            "categoryId": "6013",
            "name": "Health & Fitness",
            "storeId": "0000000000",
            "appName": "Example Calorie Tracker",
            "iconUrl": "https://example.com/icon.png",
            "day": "2026-09-06",
            "depth": 100
          }
        ],
        "storefronts": [
          {
            "country": "us",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "gb",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "fr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "de",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "br",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "be",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "jp",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "kr",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "cn",
            "day": "2026-09-06",
            "depth": 100
          },
          {
            "country": "ru",
            "day": "2026-09-06",
            "depth": 100
          }
        ]
      },
      "data": [
        {
          "storeId": "0000000000",
          "name": "Example Calorie Tracker",
          "developer": "Example Labs",
          "iconUrl": "https://example.com/icon.png",
          "appUrl": "https://apps.apple.com/us/app/id0000000000",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "releaseDate": "2024-05-01",
          "price": 0,
          "currency": "USD",
          "rating": 4.7,
          "ratingCount": 12450,
          "metadataUpdatedAt": "2026-09-06T00:15:00.000Z",
          "history": [
            {
              "day": "2026-09-06",
              "rank": 1
            }
          ],
          "rank": 1,
          "previousRank": 2,
          "movement": 1,
          "status": "ranked",
          "inCatalogue": true,
          "estimates": {
            "monthlyInstalls": {
              "kind": "range",
              "scope": "worldwide",
              "range": {
                "low": 40000,
                "mid": 84000,
                "high": 170000
              },
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": {
                "kind": "range",
                "scope": "worldwide",
                "range": {
                  "low": 34000,
                  "mid": 72000,
                  "high": 150000
                },
                "observedAt": "2026-09-05T00:00:00.000Z"
              }
            },
            "monthlyRevenue": {
              "kind": "below_floor",
              "scope": "worldwide",
              "ceiling": 5000,
              "observedAt": "2026-09-06T00:00:00.000Z",
              "previous": null
            },
            "currency": "USD"
          }
        }
      ],
      "updatedAt": "2026-09-06T00:15:00.000Z"
    }
  },
  "viewChart": {
    "query": {
      "country": "us",
      "categoryId": "6013",
      "chartType": "free",
      "view": "rankings",
      "limit": 100
    },
    "coverage": {
      "countries": [
        {
          "code": "us",
          "name": "United States"
        },
        {
          "code": "gb",
          "name": "United Kingdom"
        },
        {
          "code": "fr",
          "name": "France"
        },
        {
          "code": "de",
          "name": "Germany"
        },
        {
          "code": "br",
          "name": "Brazil"
        },
        {
          "code": "be",
          "name": "Belgium"
        },
        {
          "code": "jp",
          "name": "Japan"
        },
        {
          "code": "kr",
          "name": "South Korea"
        },
        {
          "code": "cn",
          "name": "China"
        },
        {
          "code": "ru",
          "name": "Russia"
        }
      ],
      "categories": [
        {
          "id": "all",
          "name": "Overall"
        }
      ],
      "chartTypes": [
        "free",
        "paid",
        "grossing"
      ]
    },
    "snapshot": {
      "id": "chart-snapshot-example",
      "day": "2026-09-06",
      "sourceUpdatedAt": "2026-09-06T00:00:00.000Z",
      "fetchedAt": "2026-09-06T00:15:00.000Z",
      "depth": 100,
      "previousDay": "2026-09-05",
      "stale": false
    },
    "summary": {
      "trackedApps": 1,
      "rankedApps": 1,
      "gainers": 0,
      "losers": 0,
      "newEntrants": 0,
      "newReleases": 0
    },
    "insights": {
      "categoryMix": [
        {
          "categoryId": "6013",
          "name": "Health & Fitness",
          "count": 1
        }
      ],
      "releaseAges": [
        {
          "label": "1-3years",
          "count": 1
        }
      ],
      "categoryLeaders": [
        {
          "categoryId": "6013",
          "name": "Health & Fitness",
          "storeId": "0000000000",
          "appName": "Example Calorie Tracker",
          "iconUrl": "https://example.com/icon.png",
          "day": "2026-09-06",
          "depth": 100
        }
      ],
      "storefronts": [
        {
          "country": "us",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "gb",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "fr",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "de",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "br",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "be",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "jp",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "kr",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "cn",
          "day": "2026-09-06",
          "depth": 100
        },
        {
          "country": "ru",
          "day": "2026-09-06",
          "depth": 100
        }
      ]
    },
    "data": [
      {
        "storeId": "0000000000",
        "name": "Example Calorie Tracker",
        "developer": "Example Labs",
        "iconUrl": "https://example.com/icon.png",
        "appUrl": "https://apps.apple.com/us/app/id0000000000",
        "categoryId": "6013",
        "categoryName": "Health & Fitness",
        "releaseDate": "2024-05-01",
        "price": 0,
        "currency": "USD",
        "rating": 4.7,
        "ratingCount": 12450,
        "metadataUpdatedAt": "2026-09-06T00:15:00.000Z",
        "history": [
          {
            "day": "2026-09-06",
            "rank": 1
          }
        ],
        "rank": 1,
        "previousRank": 2,
        "movement": 1,
        "status": "ranked",
        "inCatalogue": true,
        "estimates": {
          "monthlyInstalls": {
            "kind": "range",
            "scope": "worldwide",
            "range": {
              "low": 40000,
              "mid": 84000,
              "high": 170000
            },
            "observedAt": "2026-09-06T00:00:00.000Z",
            "previous": {
              "kind": "range",
              "scope": "worldwide",
              "range": {
                "low": 34000,
                "mid": 72000,
                "high": 150000
              },
              "observedAt": "2026-09-05T00:00:00.000Z"
            }
          },
          "monthlyRevenue": {
            "kind": "below_floor",
            "scope": "worldwide",
            "ceiling": 5000,
            "observedAt": "2026-09-06T00:00:00.000Z",
            "previous": null
          },
          "currency": "USD"
        }
      }
    ],
    "updatedAt": "2026-09-06T00:15:00.000Z"
  },
  "signals": {
    "country": "us",
    "weeks": [
      "2026-07-20",
      "2026-07-27",
      "2026-08-03",
      "2026-08-10",
      "2026-08-17",
      "2026-08-24",
      "2026-08-31",
      "2026-09-07"
    ],
    "keywordsObservedAt": "2026-09-10T08:40:00.000Z",
    "organicViewsCountedAt": "2026-05-29T00:00:00.000Z",
    "apps": [
      {
        "storeId": "1018368216",
        "placement": {
          "rank": 13,
          "previousRank": 10,
          "chartType": "free",
          "categoryId": "6008",
          "categoryName": "Photo & Video",
          "day": "2026-09-10"
        },
        "paid": {
          "totalAds": 30,
          "liveAds": 30,
          "startedLast7Days": 5,
          "medianDaysLive": 29,
          "longestDaysLive": 38,
          "formats": {
            "video": 29,
            "dynamic": 0,
            "image": 1
          },
          "topCallToAction": "Install now",
          "destinations": {
            "appStore": 29,
            "playStore": 0,
            "web": 1
          },
          "weeklyStarts": [
            0,
            0,
            11,
            13,
            0,
            0,
            3,
            3
          ]
        },
        "organic": {
          "matchedPosts": 10,
          "views": 29765621,
          "medianViews": 1991019,
          "bestPostViews": 7700000,
          "postsOverMillion": 7,
          "newestPublishedAt": "2026-07-29T00:00:00.000Z",
          "platforms": {
            "TikTok": 8,
            "Threads": 2
          },
          "matchedBy": "product_name"
        },
        "keywords": {
          "ranked": 20,
          "top1": 1,
          "top3": 1,
          "top10": 4,
          "top50": 9,
          "best": {
            "query": "chai",
            "position": 63,
            "popularity": 78,
            "popularityEstimate": null
          },
          "top": [
            {
              "query": "chai",
              "position": 63,
              "popularity": 78,
              "popularityEstimate": null
            },
            {
              "query": "character ai",
              "position": 47,
              "popularity": 75,
              "popularityEstimate": null
            },
            {
              "query": "talkie",
              "position": 68,
              "popularity": 74,
              "popularityEstimate": null
            }
          ]
        }
      },
      {
        "storeId": "555376968",
        "placement": {
          "rank": 1,
          "previousRank": 1,
          "chartType": "free",
          "categoryId": "6004",
          "categoryName": "Sports",
          "day": "2026-09-10"
        },
        "paid": null,
        "organic": null,
        "keywords": {
          "ranked": 29,
          "top1": 8,
          "top3": 15,
          "top10": 17,
          "top50": 20,
          "best": {
            "query": "espn fantasy",
            "position": 1,
            "popularity": 83,
            "popularityEstimate": null
          },
          "top": [
            {
              "query": "espn fantasy",
              "position": 1,
              "popularity": 83,
              "popularityEstimate": null
            },
            {
              "query": "espn",
              "position": 2,
              "popularity": 78,
              "popularityEstimate": null
            },
            {
              "query": "yahoo fantasy",
              "position": 2,
              "popularity": 78,
              "popularityEstimate": null
            },
            {
              "query": "fantasy football draft",
              "position": 3,
              "popularity": null,
              "popularityEstimate": {
                "tier": "medium",
                "method": "peekpanda_popularity_estimate",
                "country": "us",
                "estimatedAt": "2026-09-07T04:00:00.000Z",
                "modelTrainedAt": "2026-09-07T03:55:00.000Z"
              }
            }
          ]
        }
      }
    ]
  }
}

```

## Source

Chart placements come from dated public App Store chart observations. Paid ads are collected per chosen app, so an app without ads has not been collected. An ad counts for the app its own verified App Store link names, or for the app its proven advertiser page runs ads for, web funnels and Google Play links included; the paid pulse counts the same ads. destinations splits them into App Store, Play Store and web-funnel ads, and only App Store ads are counted as appStore. "Last 7 days" and run lengths are UTC calendar days. Organic posts are matched by product name, not account ownership, and their views are as last counted. Keyword positions are observed App Store search result positions, not search volume. Each signals keyword carries popularity, Apple's weekly search popularity (1 to 100), or null when Apple reports nothing. Where Apple reports nothing for a US keyword, popularityEstimate carries PeekPanda's own tier (very_low, low, medium or high) with estimatedAt and the modelTrainedAt of the weekly model behind it, never a number on Apple's scale. popularityEstimate is null whenever popularity is set and on every non-US storefront. Neither is a search count.

## Refresh

This GET reads stored evidence only. It combines existing chart, overview and bounded signal reads under one access check; it never calls Apple or an advertising library.

## Rate limits

Market reads share the standard read budget of 60 requests per minute with every other PeekPanda read. During the preview the count is kept per client network address, not per plan, and it resets at the end of each one-minute window. A 429 rate_limited response carries Retry-After when the server can say how long to wait: wait that many seconds, then send the same request again. Every call also counts toward your plan's daily API and MCP allowance: 30 calls a day on Peek and 1,000 on Panda, shared by every key and MCP connection on the plan and reset at 00:00 UTC. Past it, calls answer 429 daily_call_limit until the reset. Stored reads do not use your refresh allowance.

## Bounded response

Three overall charts and a category-selected chart carry at most 100 rows each. For categoryId=all, viewChart is null and the selected chart is charts[chartType], so it is sent once. Signals are deduplicated and capped at 600 app IDs. The endpoint has no cursor.