PeekPanda markpeekpandaDocumentation
For your AI
Copy pageCopy entire docs
Dashboard

Read paid-ad rankings

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

Download Markdown ↓

GEThttps://api.peekpanda.com/v1/paid-ads/intelligence

Request

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

Parameters

NameInTypeRequiredDescription
advertiserExternalIdquerystringNoLimit the ranking to one advertiser.
categoryquerycategoryNoLimit the ranking to one category.
platformquerymeta | tiktokNoAdvertising platform.
advertiserLimitqueryinteger, 1-400NoAdvertisers to return. Defaults to 25.
cadenceWeeksqueryinteger, 4-52NoUTC Monday weeks of creatives started and stopped. Defaults to 12.

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.

Response fields

generatedAtstring
scopenull
totals.adsnumber
totals.liveAdsnumber
totals.advertisersnumber
totals.liveAdvertisersnumber
totals.newAdsLast7Daysnumber
totals.advertisersShippingLast7Daysnumber
totals.stoppedLast7Daysnumber
totals.halfLifeDaysnumber
totals.stillRunningAt30Daysnumber
totals.medianRunDaysnumber
totals.longestRunDaysnumber
totals.liveBeyond60Daysnumber
totals.reachDisclosedAdsnumber
totals.unlinkedAdsnumber
totals.uncategorizedLiveAdsnumber
advertisers[].advertiserExternalIdstring
advertisers[].namestring
advertisers[].productExternalIdstring
advertisers[].productIconUrlnull
advertisers[].categorystring
advertisers[].liveAdsnumber
advertisers[].totalAdsnumber
advertisers[].newLast7Daysnumber
advertisers[].liveBeyond30Daysnumber
advertisers[].weeklyNewAds[]number[]
advertisers[].medianRunDaysnumber
advertisers[].longestRunDaysnumber
advertisers[].formatMix.videonumber
advertisers[].formatMix.imagenumber
advertisers[].formatMix.carouselnumber
advertisers[].formatMix.dynamicnumber
advertisers[].formatMix.unknownnumber
advertisers[].topCtastring
advertisers[].topDestinationKindstring
advertisers[].storeRatingnumber
advertisers[].storeRatingCountnumber
longevity[].bandstring
longevity[].countnumber
formats[].keystring
formats[].labelstring
formats[].countnumber
ctas[].keystring
ctas[].labelstring
ctas[].countnumber
destinations[].keystring
destinations[].labelstring
destinations[].countnumber
categories[].categorystring
categories[].advertisersnumber
categories[].liveAdsnumber
categories[].newLast7Daysnumber
categories[].medianRunDaysnumber
categories[].stillRunningAt30Daysnumber
categories[].halfLifeDaysnumber
cadence[].weekStartstring
cadence[].newAdsnumber
cadence[].advertisersnumber
cadence[].stoppedAdsnumber
cadence[].isPartialboolean
survival[].formatstring
survival[].adsnumber
survival[].stillRunning[]number[]
lastingFactors[].factorstring
lastingFactors[].slices[].keystring
lastingFactors[].slices[].labelstring
lastingFactors[].slices[].adsnumber
lastingFactors[].slices[].stillRunningAt30Daysnumber

Authentication

Requires Bearer API credential or OAuth access token. Scope context:read. MCP calls get_ads with action intelligence.

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

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

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.

AI agent or LLM? Read this page as markdown