Facebook Ads

Every ad on Meta's platforms is public in the Ad Library. This endpoint pulls a page's ads with copy, creative format, call to action, platforms, start date and landing page, so you can see what a competitor is spending on and for how long. An ad that has run for months is an ad that works.

POST/v1/social/facebook/ads

Page ads

Returns ads for a Facebook page. Works for any advertiser, not only pages you manage.

Costs 0.9 credits per ad, rounded to the nearest half credit. 10 ads is 9 credits.

Required attributes

Name
page
Type
string
Description
A Facebook page URL or slug, for example nike or https://www.facebook.com/nike.

Optional attributes

Name
status
Type
string
Description
active, inactive or all. Default active.
Name
limit
Type
integer
Description
Ads to fetch, 5 to 20. Default 10. Capped by your plan.

Response fields

Name
ads[].days_running
Type
integer
Description
Days since the ad started. Long running ads are the ones worth studying.
Name
ads[].format
Type
string
Description
image, video, carousel or unknown.
Name
ads[].cta
Type
string
Description
The call to action button label, lower case.
Name
ads[].variants
Type
integer
Description
How many creative variants share this ad. More than 1 means an A/B test.

Request

POST

/v1/social/facebook/ads

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/social/facebook/ads \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": "nike", "status": "active", "limit": 10}'

Response

{
  "data": {
    "page": "https://www.facebook.com/nike",
    "status": "active",
    "checked_at": "2026-09-09T11:44:52.118Z",
    "count": 10,
    "active": 10,
    "ads": [
      {
        "id": "1702938977100376",
        "page_name": "Nike",
        "is_active": true,
        "started_at": "2025-04-07",
        "days_running": 521,
        "format": "carousel",
        "platforms": [
          "facebook",
          "instagram",
          "audience_network",
          "messenger"
        ],
        "headline": "{{product.name}}",
        "text": "Bring sports more fully into your day with the Nike App.",
        "cta": "install mobile app",
        "landing_url": "http://itunes.apple.com/app/id1095459556",
        "landing_domain": "itunes.apple.com",
        "image_url": "https://scontent.xx.fbcdn.net/v/t39.35426-6/431748186_289316047369916.jpg",
        "variants": 3
      },
      // ...
    ]
  },
  "meta": {
    "credits_charged": 9,
    "credits_remaining": 462,
    "request_id": "e4b1c2d3-8f90-4a1b-9c2d-3e4f5a6b7c8d"
  }
}