PeekPanda markpeekpandaDocumentationFor AI ↗Open app

PeekPanda docs

Read paid-ad rankings

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

Download Markdown ↓
GET/v1/paid-ads/intelligence
Auth Bearer API credential or OAuth access tokenScope context:readMCP get_ads action intelligence

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'

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": []
}

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"
    }
  }
}

Parameters

NameInTypeRequiredDescription
advertiserExternalIdquerystringNoLimit the ranking to one advertiser.
categoryquerycategoryNoLimit the ranking to one category.
platformquerymeta | tiktokNoAdvertising platform.
advertiserLimitqueryinteger, 1-50NoAdvertisers to return. Defaults to 25.
cadenceWeeksqueryinteger, 4-52NoISO weeks of new-creative cadence. Defaults to 12.

Known errors

400invalid_request for an invalid filter, identity or limit.
401authentication_required for a missing or invalid credential.
402subscription_required when access is not entitled.
403authorization_required for a missing scope or unavailable preview access.
404not_found when the record is outside the accessible catalogue.
429rate_limited; honor Retry-After when present.

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.