# Read paid-ad rankings

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

## 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/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-50 | no | Advertisers to return. Defaults to 25. |
| `cadenceWeeks` | query | integer, 4-52 | no | ISO weeks of new-creative cadence. 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.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.

## 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. advertisers, longevity, formats, ctas, destinations, categories and cadence are empty when nothing is stored. scope is null for the unfiltered library.

```
{
  "generatedAt": "2026-09-06T00:00:00.000Z",
  "scope": null,
  "totals": {
    "ads": 0,
    "liveAds": 0,
    "advertisers": 0,
    "liveAdvertisers": 0,
    "newAdsLast7Days": 0,
    "advertisersShippingLast7Days": 0,
    "medianRunDays": null,
    "longestRunDays": null,
    "liveBeyond60Days": 0,
    "reachDisclosedAds": 0,
    "unlinkedAds": 0
  },
  "advertisers": [],
  "longevity": [],
  "formats": [],
  "ctas": [],
  "destinations": [],
  "categories": [],
  "cadence": []
}

```

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