# Chart one app's paid ads

Chart one competitor app's paid ads: launches, run lengths and creative mixes, for all of its advertisers or one.

## 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/competitors/{platform}/{storeId}/paid-ads/intelligence

- Method: `GET`
- Path: `/v1/competitors/{platform}/{storeId}/paid-ads/intelligence`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_ads`
- MCP action: `app_intelligence`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `platform` | path | ios | yes | The preview supports iOS only. |
| `storeId` | path | numeric string | yes | Apple App Store identifier. |
| `advertiserExternalId` | query | string | no | Narrow the charts to one of the advertisers the response lists. Omit it for all of them. |

## 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

Identify the listing. Every chart covers all of its advertisers unless you name one.

```
curl --get 'https://api.peekpanda.com/v1/competitors/ios/0000000000/paid-ads/intelligence' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'advertiserExternalId=example-page'
```

## MCP request

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

```
{
  "name": "get_ads",
  "arguments": {
    "request": {
      "action": "app_intelligence",
      "params": {
        "platform": "<platform>",
        "storeId": "<storeId>"
      }
    }
  }
}

```

## Response

advertisers lists every advertiser of the app, whichever one the charts narrow to. Days are whole UTC days, the same windows the case file reads. weeks holds 26 Monday weeks, oldest first; liveAds is the part of newAds still live now. longestRunning uses the Search paid ads item shape with short-lived media URLs. medianRunDays and longestRunDays are null when no ad is live.

```
{
  "generatedAt": "2026-09-06T00:00:00.000Z",
  "storeId": "0000000000",
  "advertiserExternalId": null,
  "advertisers": [],
  "totals": {
    "ads": 27,
    "liveAds": 4,
    "advertisers": 1,
    "newAdsLast7Days": 2,
    "newAdsLast30Days": 5,
    "medianRunDays": 12,
    "longestRunDays": 188
  },
  "weeks": [
    {
      "weekStart": "2026-03-09",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-03-16",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-03-23",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-03-30",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-04-06",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-04-13",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-04-20",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-04-27",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-05-04",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-05-11",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-05-18",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-05-25",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-06-01",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-06-08",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-06-15",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-06-22",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-06-29",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-07-06",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-07-13",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-07-20",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-07-27",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-08-03",
      "newAds": 1,
      "liveAds": 0
    },
    {
      "weekStart": "2026-08-10",
      "newAds": 1,
      "liveAds": 1
    },
    {
      "weekStart": "2026-08-17",
      "newAds": 1,
      "liveAds": 1
    },
    {
      "weekStart": "2026-08-24",
      "newAds": 1,
      "liveAds": 1
    },
    {
      "weekStart": "2026-08-31",
      "newAds": 2,
      "liveAds": 1
    }
  ],
  "longevity": [
    {
      "band": "0-6",
      "count": 0
    },
    {
      "band": "7-14",
      "count": 0
    },
    {
      "band": "15-30",
      "count": 0
    },
    {
      "band": "31-60",
      "count": 0
    },
    {
      "band": "61-90",
      "count": 0
    },
    {
      "band": "90+",
      "count": 1
    }
  ],
  "longestRunning": [],
  "formats": [
    {
      "key": "video",
      "label": "Video",
      "count": 27
    }
  ],
  "ctas": [
    {
      "key": "install now",
      "label": "Install now",
      "count": 20
    }
  ],
  "destinations": [
    {
      "key": "app_store",
      "label": "App Store",
      "count": 27
    }
  ]
}

```

## Source

Stored paid-ad observations. An ad belongs to the app its own verified App Store link names. There is no spend, impression, reach or country field: Meta does not publish them.

## Refresh

These reads do not collect new ads.