# Read paid-ad rankings

Rank advertisers by how many creatives they ship and how long those creatives stay live.

## Endpoint: GET /v1/paid-ads/intelligence

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `advertiserExternalId` | query | string | no | Limit the ranking to one advertiser. |
| `category` | query | category | no | Limit the ranking to one category. |
| `platform` | query | meta | tiktok | no | Advertising platform. |
| `advertiserLimit` | query | integer, 1-400 | no | Advertisers to return. Defaults to 25. |
| `cadenceWeeks` | query | integer, 4-52 | no | UTC Monday weeks of creatives started and stopped. Defaults to 12. |

## 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.
- 403 workspace_not_accessible when x-genviral-tenancy names a workspace the credential cannot reach.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.
- 429 daily_call_limit; the plan's daily API and MCP calls are used until 00:00 UTC.

## Request

Every filter is optional. This read never starts collection and never ranks on money.

```
curl --get 'https://api.peekpanda.com/v1/paid-ads/intelligence' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal'
```

## MCP request

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

```
{
  "name": "get_ads",
  "arguments": {
    "request": {
      "action": "intelligence"
    }
  }
}

```

## Response

totals cover the stored library in scope; scope is null for the unfiltered library. uncategorizedLiveAds counts live ads whose advertiser resolves to no category, so on the unfiltered library the liveAds of the category rows plus uncategorizedLiveAds equals liveAds; unlinkedAds counts ads, live or stopped, that belong to no app: no verified App Store link of their own and no proven advertiser page. A web-funnel or Google Play ad of a proven advertiser belongs to its app and is not counted. Ad survival is the share of the ads we collected that were still running N days after launch, estimated with Kaplan–Meier: a stopped ad counts on the day it stopped, a live ad only up to its current age, so a young ad never reads as stopped. survival holds one curve per format (all, video, dynamic, image) with stillRunning[0] at launch and stillRunning[90] at 90 days; a format with no ads is left out. halfLifeDays is the first day half the ads have stopped, null when more than half still run at 90 days. stillRunningAt30Days is day 30 of the same curve. lastingFactors compares that day-30 reading across button text (the most-used calls to action) and body-copy length (every band, in order); a band with no ads has a null reading. cadence counts new and stopped ads per week; isPartial marks the week still being counted. Each advertiser carries liveBeyond30Days and weeklyNewAds, 12 weeks oldest first. These figures describe ads we collected. They are not spend or performance. Right after an update the stored figures can still be rebuilding: the read then answers 503 with error code projection_warming and a Retry-After header, never an empty market.

```
{
  "generatedAt": "2026-09-24T09:00:00.000Z",
  "scope": null,
  "totals": {
    "ads": 1200,
    "liveAds": 360,
    "advertisers": 12,
    "liveAdvertisers": 9,
    "newAdsLast7Days": 48,
    "advertisersShippingLast7Days": 4,
    "stoppedLast7Days": 31,
    "halfLifeDays": 12,
    "stillRunningAt30Days": 0.3,
    "medianRunDays": 9,
    "longestRunDays": 188,
    "liveBeyond60Days": 40,
    "reachDisclosedAds": 0,
    "unlinkedAds": 25,
    "uncategorizedLiveAds": 20
  },
  "advertisers": [
    {
      "advertiserExternalId": "example-page",
      "name": "Example Fitness",
      "productExternalId": "0000000000",
      "productIconUrl": null,
      "category": "Health & Wellness",
      "liveAds": 64,
      "totalAds": 210,
      "newLast7Days": 9,
      "liveBeyond30Days": 22,
      "weeklyNewAds": [
        6,
        4,
        8,
        5,
        7,
        9,
        6,
        10,
        8,
        7,
        11,
        3
      ],
      "medianRunDays": 14,
      "longestRunDays": 188,
      "formatMix": {
        "video": 150,
        "image": 10,
        "carousel": 0,
        "dynamic": 50,
        "unknown": 0
      },
      "topCta": "Install now",
      "topDestinationKind": "app_store",
      "storeRating": 4.7,
      "storeRatingCount": 12000
    }
  ],
  "longevity": [
    {
      "band": "0-6",
      "count": 120
    },
    {
      "band": "7-14",
      "count": 70
    },
    {
      "band": "15-30",
      "count": 60
    },
    {
      "band": "31-60",
      "count": 70
    },
    {
      "band": "61-90",
      "count": 25
    },
    {
      "band": "90+",
      "count": 15
    }
  ],
  "formats": [
    {
      "key": "video",
      "label": "Video",
      "count": 780
    },
    {
      "key": "dynamic",
      "label": "Dynamic",
      "count": 380
    },
    {
      "key": "image",
      "label": "Image",
      "count": 40
    },
    {
      "key": "carousel",
      "label": "Carousel",
      "count": 0
    },
    {
      "key": "unknown",
      "label": "Unknown",
      "count": 0
    }
  ],
  "ctas": [
    {
      "key": "install now",
      "label": "Install now",
      "count": 520
    }
  ],
  "destinations": [
    {
      "key": "app_store",
      "label": "App Store",
      "count": 1100
    },
    {
      "key": "web",
      "label": "Web",
      "count": 100
    },
    {
      "key": "play_store",
      "label": "Play Store",
      "count": 0
    },
    {
      "key": "unknown",
      "label": "Unknown",
      "count": 0
    }
  ],
  "categories": [
    {
      "category": "Health & Wellness",
      "advertisers": 5,
      "liveAds": 160,
      "newLast7Days": 20,
      "medianRunDays": 10,
      "stillRunningAt30Days": 0.33,
      "halfLifeDays": 14
    }
  ],
  "cadence": [
    {
      "weekStart": "2026-07-06",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-07-13",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-07-20",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-07-27",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-08-03",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-08-10",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-08-17",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-08-24",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-08-31",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-09-07",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-09-14",
      "newAds": 40,
      "advertisers": 6,
      "stoppedAds": 35,
      "isPartial": false
    },
    {
      "weekStart": "2026-09-21",
      "newAds": 18,
      "advertisers": 3,
      "stoppedAds": 9,
      "isPartial": true
    }
  ],
  "survival": [
    {
      "format": "all",
      "ads": 1200,
      "stillRunning": [
        1,
        0.932,
        0.87,
        0.812,
        0.758,
        0.709,
        0.664,
        0.622,
        0.583,
        0.547,
        0.515,
        0.484,
        0.456,
        0.43,
        0.406,
        0.384,
        0.364,
        0.345,
        0.328,
        0.312,
        0.297,
        0.283,
        0.271,
        0.259,
        0.248,
        0.238,
        0.229,
        0.221,
        0.213,
        0.206,
        0.199,
        0.193,
        0.188,
        0.182,
        0.178,
        0.173,
        0.169,
        0.165,
        0.162,
        0.159,
        0.156,
        0.153,
        0.15,
        0.148,
        0.146,
        0.144,
        0.142,
        0.14,
        0.139,
        0.137,
        0.136,
        0.135,
        0.134,
        0.133,
        0.132,
        0.131,
        0.13,
        0.129,
        0.128,
        0.128,
        0.127,
        0.127,
        0.126,
        0.126,
        0.125,
        0.125,
        0.124,
        0.124,
        0.124,
        0.123,
        0.123,
        0.123,
        0.123,
        0.123,
        0.122,
        0.122,
        0.122,
        0.122,
        0.122,
        0.122,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121
      ]
    },
    {
      "format": "video",
      "ads": 780,
      "stillRunning": [
        1,
        0.926,
        0.859,
        0.797,
        0.74,
        0.688,
        0.641,
        0.597,
        0.557,
        0.52,
        0.487,
        0.456,
        0.428,
        0.402,
        0.378,
        0.357,
        0.337,
        0.319,
        0.302,
        0.287,
        0.273,
        0.26,
        0.248,
        0.238,
        0.228,
        0.219,
        0.21,
        0.203,
        0.196,
        0.19,
        0.184,
        0.178,
        0.173,
        0.169,
        0.165,
        0.161,
        0.158,
        0.155,
        0.152,
        0.149,
        0.147,
        0.144,
        0.142,
        0.14,
        0.139,
        0.137,
        0.136,
        0.134,
        0.133,
        0.132,
        0.131,
        0.13,
        0.129,
        0.129,
        0.128,
        0.127,
        0.127,
        0.126,
        0.125,
        0.125,
        0.125,
        0.124,
        0.124,
        0.124,
        0.123,
        0.123,
        0.123,
        0.122,
        0.122,
        0.122,
        0.122,
        0.122,
        0.122,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12
      ]
    },
    {
      "format": "dynamic",
      "ads": 380,
      "stillRunning": [
        1,
        0.942,
        0.887,
        0.836,
        0.788,
        0.744,
        0.703,
        0.664,
        0.628,
        0.594,
        0.562,
        0.533,
        0.506,
        0.48,
        0.456,
        0.434,
        0.413,
        0.393,
        0.375,
        0.358,
        0.342,
        0.328,
        0.314,
        0.301,
        0.289,
        0.278,
        0.267,
        0.257,
        0.248,
        0.24,
        0.232,
        0.224,
        0.217,
        0.211,
        0.205,
        0.199,
        0.194,
        0.189,
        0.185,
        0.18,
        0.176,
        0.172,
        0.169,
        0.166,
        0.163,
        0.16,
        0.157,
        0.155,
        0.152,
        0.15,
        0.148,
        0.146,
        0.145,
        0.143,
        0.141,
        0.14,
        0.139,
        0.137,
        0.136,
        0.135,
        0.134,
        0.133,
        0.132,
        0.132,
        0.131,
        0.13,
        0.129,
        0.129,
        0.128,
        0.128,
        0.127,
        0.127,
        0.126,
        0.126,
        0.125,
        0.125,
        0.125,
        0.124,
        0.124,
        0.124,
        0.124,
        0.123,
        0.123,
        0.123,
        0.123,
        0.123,
        0.122,
        0.122,
        0.122,
        0.122,
        0.122
      ]
    },
    {
      "format": "image",
      "ads": 40,
      "stillRunning": [
        1,
        0.87,
        0.758,
        0.664,
        0.583,
        0.515,
        0.456,
        0.406,
        0.364,
        0.328,
        0.297,
        0.271,
        0.248,
        0.229,
        0.213,
        0.199,
        0.188,
        0.178,
        0.169,
        0.162,
        0.156,
        0.15,
        0.146,
        0.142,
        0.139,
        0.136,
        0.134,
        0.132,
        0.13,
        0.128,
        0.127,
        0.126,
        0.125,
        0.124,
        0.124,
        0.123,
        0.123,
        0.122,
        0.122,
        0.122,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.121,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12,
        0.12
      ]
    }
  ],
  "lastingFactors": [
    {
      "factor": "cta",
      "slices": [
        {
          "key": "install now",
          "label": "Install now",
          "ads": 520,
          "stillRunningAt30Days": 0.26
        },
        {
          "key": "learn more",
          "label": "Learn more",
          "ads": 210,
          "stillRunningAt30Days": 0.32
        }
      ]
    },
    {
      "factor": "copy_length",
      "slices": [
        {
          "key": "none",
          "label": "No text",
          "ads": 90,
          "stillRunningAt30Days": 0.22
        },
        {
          "key": "1-50",
          "label": "1-50",
          "ads": 540,
          "stillRunningAt30Days": 0.26
        },
        {
          "key": "51-125",
          "label": "51-125",
          "ads": 350,
          "stillRunningAt30Days": 0.4
        },
        {
          "key": "126-250",
          "label": "126-250",
          "ads": 150,
          "stillRunningAt30Days": 0.36
        },
        {
          "key": "251-500",
          "label": "251-500",
          "ads": 70,
          "stillRunningAt30Days": 0.3
        },
        {
          "key": "500+",
          "label": "500+",
          "ads": 0,
          "stillRunningAt30Days": null
        }
      ]
    }
  ]
}

```

## Source

Stored paid-ad observations. Rankings count creatives and how long they stay live. There is no spend or impression field.

## Refresh

These reads do not collect new ads.