Skip to content

Apps · MCP TOOL

get_listing_changes

Read when an app's store listing changed, with each before and after.

Set up your assistant · Authentication and errors

When to use it

Check when a competitor renamed its app, rewrote its description, swapped its icon or screenshots, or changed its price. Newest first; price changes are for the app's own storefront and come on top of limit. Continue with before = nextBefore.

Parameters

NameTypeRequiredDefaultAllowed valuesDescription
appIdstringYes——"ios:284882215", "android:com.example.app", or a bare id together with `source` Minimum length: 1. Maximum length: 210.
limitintegerNo20—text and image change records per page; price changes in the same period come on top Minimum: 1. Maximum: 50.
beforestringNo——the `nextBefore` of the previous page Minimum length: 1. Maximum length: 2048.

Defaults and constraints come from the published Zod input schema. “—” means no schema default or no enum restriction. Use JSON values of the listed type; additional handler rules are described above.

Example prompts

  • What did Calm change on its App Store listing this month?

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_listing_changes",
    "arguments": {
      "appId": "ios:571800810",
      "limit": 10
    }
  }
}

Example result

Illustrative, abridged JSON-RPC result. Only selected fields are shown; empty arrays illustrate a response with no rows. These are not current catalog observations. Parse the JSON inside content[].text.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[{\"id\":\"3f9a1c2b7d4e\",\"detectedAt\":\"2026-11-05T10:12:00.000Z\",\"storefront\":\"us\",\"changes\":[{\"field\":\"title\",\"before\":\"Calm - Sleep & Meditation\",\"after\":\"Calm: Sleep & Meditation\"}]},{\"id\":\"price:us:2026-11-01\",\"detectedAt\":\"2026-11-01T00:00:00.000Z\",\"storefront\":\"us\",\"changes\":[{\"field\":\"price\",\"before\":{\"price\":0,\"currency\":\"USD\"},\"after\":{\"price\":4.99,\"currency\":\"USD\"}}]}],\"nextBefore\":null,\"trackingSince\":{\"text\":\"2026-11-12\",\"price\":\"2026-09-02\"}}"
      }
    ]
  }
}

Free vs paid results

Basic and Pro only: a Free account or a key without a user gets a plan_required error naming the plans.

Paid access does not fill coverage gaps or unknown values. Returned plan metadata and lock notes explain redaction where applicable. Read the full Free data policy.

Rate limits and usage credit

PlanCalls per tool / dayAll tools / week
Free10100
Basic2001,400
Pro6005,000

Days reset at 00:00 UTC. The combined ISO week resets Monday at 00:00 UTC. Every served tool call counts, including cached reads. Failed or refused calls are released along with any charge. Compare plans.

After either allowance, Basic and Pro can opt in to pay $0.02 in usage credit per call to get_listing_changes. A call exceeding both windows is charged once. Free is refused past its allowances; paid plans without opt-in or enough credit are also refused with HTTP 402 / JSON-RPC -32004.

Credential request throttles and, for live keyword work, store-work throttles also apply. Follow retry instructions in the error reference.