Search paid ads

Search stored Meta and TikTok ad-library observations.

Last reviewed October 19, 2026Download Markdown ↓

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

Request

Send the documented filters as query parameters. To follow an app or advertiser over time, pass storeIds or advertiserExternalId with sort=recently_discovered and set discoveredAfter to the newest discoveredAt you already read. This read does not collect new ads.

Parameters

NameInTypeRequiredDescription

cursorqueryopaque stringNoCursor returned by the previous page.

limitqueryinteger, 1–40NoPage size; defaults to 18.

searchquerystring, max 120NoSearch stored lexical evidence across creative copy, transcripts, creative analysis, advertiser names and linked apps. A recognized category term may include related-category matches when includeRelated=true.

searchScopequeryall | creative | apps | advertisersNoLimit the search fields; defaults to all.

includeRelatedqueryboolean | true | falseNoInclude related-category matches. Disabled by default.

excludeAdvertiserquerystring, 1–120NoExclude one exact advertiser name from the returned page.

groupCreativesqueryboolean | true | falseNoGroup ads that share an exact media asset and return their SHA-256 group keys. Requires a ranked sort: Best match with a nonblank search or a ranked browse order.

creativeGroupKeyquery64 lowercase hexadecimal charactersNoFilter to one exact creative asset group; pass groupCreatives=false to expand its ads. Requires a ranked sort; balanced browsing is not supported.

platformquerymeta | tiktokNoAdvertising platform filter.

statusquerycomma-separated list of active | inactive | unknownNoObserved ad status; matches any listed value, e.g. status=active,inactive. A single value works as before.

advertiserquerystring, max 120NoExact, case-sensitive advertiser name.

advertiserExternalIdquerystring, 1–255NoOne advertiser by its exact platform page id (a Meta page id). Prefer it over advertiser.

archiveIdquerystring, 1–255NoExact platform archive id filter.

productExternalIdquerystring, max 255NoInclude ads linked to this exact app store id.

excludeProductExternalIdquerystring, max 255NoExclude ads linked to this exact app store id.

storeIdsquerycomma-separated numeric App Store IDs, max 25NoOnly ads verified to link to these apps: the same ads the app’s paid intelligence counts.

formatquerycomma-separated list of image | video | carousel | dynamic | unknownNoCreative format filter; matches any listed value, e.g. format=video,carousel. dynamic is Meta dynamic creative (DCO), often a static image.

startDatequeryYYYY-MM-DDNoEarliest disclosed ad start date, inclusive.

endDatequeryYYYY-MM-DDNoLatest disclosed ad start date, inclusive.

minRunDaysquery7 | 30 | 90 | 180 | 365NoMinimum run length. Live ads count to now; stopped ads to their disclosed end.

discoveredAfterqueryISO 8601 date-timeNoOnly ads PeekPanda first recorded strictly after this instant.

ctaquerypresent | missingNoWhether the creative has a call to action.

copyLengthqueryshort | medium | longNoPrimary-text length bucket.

reachqueryreported | 10000 | 100000 | 1000000NoRequire reported reach, optionally above a threshold.

appLinkquerylinked | unlinkedNoWhether the ad has a verified App Store match.

savedqueryboolean | true | falseNoWhen true, only account-saved ads.

sortqueryrelevance | balanced | recently_discovered | newest_started | longest_running | most_tested | highest_reported_reachNoDefaults to relevance for nonblank search text, recently_discovered for a storeIds browse, and balanced otherwise. Explicit relevance without search text becomes that browse default. Relevance ranks lexical evidence with advertiser diversity. longest_running is the closest performance proxy: no spend is published.

Response

items are stored paid-ad observations. Search uses lexical evidence already stored in the corpus; it does not fetch new provider data. Relevance ranks matching evidence with advertiser diversity. Creative grouping and creativeGroupKey require a ranked sort; balanced browsing returns HTTP 400 for these options. Expand one group by passing its key with groupCreatives=false. Each item may include searchMatch.sources and an exact-asset creativeGroup (SHA-256 key, count and representative archive id). Group counts describe ads sharing identical media, not identical copy. Use creativeGroupKey to filter one exact group. searchSummary counts only the returned page, never the matching corpus. Keep filters and sort unchanged while following nextCursor so pages continue the same ordered search. A storeIds read is served from the stored ad list of those apps, about a minute behind new ads; without sort or search it lists them by recently_discovered (sort=balanced still mixes advertisers). With sort=recently_discovered or newest_started it reads that list in order and checks each other filter on the ads it scans, at most 4,096 per request, so a rare filter can return a short or empty page with hasMore true: keep following nextCursor until hasMore is false. Other sorts, balanced included, rank the listed ads of those apps. canonicalKey matches paid:(meta|tiktok):{archiveId}. performance is unavailable or a reported_reach disclosure. There is no spend field.

Response fields

items[].idstring

items[].canonicalKeystring

items[].sourcestring

items[].platformstring

items[].archiveIdstring

items[].advertiser.externalIdstring

items[].advertiser.namestring

items[].statusstring

items[].startedAtstring

items[].endedAtnull

items[].discoveredAtstring

items[].sourceUrlstring

items[].creative.formatstring

items[].creative.hookstring

items[].creative.bodystring

items[].creative.titlestring

items[].creative.descriptionnull

items[].creative.ctaTextstring

items[].creative.imageUrls[]string[]

items[].creative.videoUrls[]string[]

items[].creative.unitsarray

items[].productLink.kindstring

items[].productLink.namestring

items[].productLink.urlstring

items[].productLink.externalIdnull

items[].productLink.confidencestring

items[].destination.kindstring

items[].destination.urlstring

items[].destination.hoststring

items[].destination.pagestring

items[].destination.appStoreIdnull

items[].productIconUrlnull

items[].performance.kindstring

items[].savedboolean

nextCursornull

hasMoreboolean

searchSummary.returnedAdsnumber

searchSummary.returnedAdvertisersnumber

searchSummary.returnedAppsnumber

searchSummary.groupedboolean

Authentication

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

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 search. Path fields go in params, filters in query, and a write body in body.

{
  "name": "get_ads",
  "arguments": {
    "request": {
      "action": "search"
    }
  }
}

Source

Stored public advertising-library observations with source dates. Spend is unavailable unless the public record reports it.

Refresh

This read returns stored observations. Saving an ad changes boards only.

AI agent or LLM? Read this page as markdown