PeekPanda markpeekpandaDocumentationFor AI ↗Open app

PeekPanda docs

Search paid ads

Search stored Meta and TikTok ad-library observations.

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

Request

Send peekPandaPaidAdQuerySchema filters as query parameters. This read does not collect new ads.

curl --get 'https://api.peekpanda.com/v1/paid-ads' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'platform=meta' \
  --data-urlencode 'limit=18' \
  --data-urlencode 'sort=recently_discovered'

Response

items are stored paid-ad observations. canonicalKey matches paid:(meta|tiktok):{archiveId}. performance is unavailable or a reported_reach disclosure. There is no spend field.

{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "canonicalKey": "paid:meta:111222333",
      "source": "paid",
      "platform": "meta",
      "archiveId": "111222333",
      "advertiser": {
        "externalId": "444555666",
        "name": "Example Advertiser"
      },
      "status": "active",
      "startedAt": "2026-08-01T00:00:00.000Z",
      "endedAt": null,
      "discoveredAt": "2026-09-06T00:00:00.000Z",
      "sourceUrl": "https://www.facebook.com/ads/library?id=111222333",
      "creative": {
        "format": "video",
        "hook": "Turn saved recipes into a grocery list",
        "body": "Turn saved recipes into a grocery list.",
        "title": "Example Meal Planner",
        "description": null,
        "ctaText": "Download",
        "imageUrls": [
          "https://cdn.example.com/ad.jpg"
        ],
        "videoUrls": [
          "https://cdn.example.com/ad.mp4"
        ],
        "units": []
      },
      "productLink": {
        "kind": "official_domain",
        "name": "Example Meal Planner",
        "url": "https://example.com",
        "externalId": null,
        "confidence": "unresolved"
      },
      "productIconUrl": null,
      "performance": {
        "kind": "unavailable"
      },
      "saved": false
    }
  ],
  "nextCursor": null,
  "hasMore": false,
  "total": 1,
  "reportedReachCount": 0
}

Parameters

NameInTypeRequiredDescription
cursorqueryopaque stringNoCursor returned by the previous page.
limitqueryinteger, 1–40NoPage size; defaults to 18.
searchquerystring, max 120NoAdvertiser or creative search text.
platformquerymeta | tiktokNoAdvertising platform filter.
statusqueryactive | inactive | unknownNoObserved ad status.
advertiserquerystring, max 120NoAdvertiser name filter.
formatqueryimage | video | carousel | dynamic | unknownNoCreative format filter.
savedqueryboolean | true | falseNoWhen true, only account-saved ads.
sortqueryrecently_discovered | newest_started | highest_reported_reachNoDefaults to recently_discovered.

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 Meta/TikTok ad-library observations (scrapecreators or direct Meta). Not Apple. No spend field.

Refresh

Paid-ad ingestion is a separate operator path; this GET is a stored read. Save/remove are account bookmarks.