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, or every advertiser's ads that match a keyword in one country. Works for any advertiser, not only pages you manage.

Costs 1.43 credits per ad in either mode. 10 ads is 14.3 credits.

Required attributes

One of the two. Give page to audit one advertiser, keyword to see who is paying to reach a theme.

Name
page
Type
string
Description
A Facebook page URL or slug, for example nike or https://www.facebook.com/nike.
Name
keyword
Type
string
Description
Words the ad copy has to contain, searched across every advertiser in the Ad Library. The response adds an advertisers list with the page names found.

Optional attributes

Name
country
Type
string
Description
Keyword mode only. ISO 3166-1 alpha-2 code of the country the ads are shown in, for example US, ES or MX. Default US.
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"
  }
}

POST/v1/social/facebook/page

Page

The advertiser itself rather than its ads: name, category, likes, followers, rating, contact details, website, and whether the page is running ads right now. Ask for up to ten pages in one call to line a client up against its competitors.

Costs 2.34 credits per page. One page is 2.4 credits, five pages 11.7.

Use it before the ads endpoint: this tells you who is worth looking at and whether they are currently spending, and running_ads tells you whether a call to /v1/social/facebook/ads will return anything.

Required attributes

Name
pages
Type
array
Description
1 to 10 page URLs or slugs. nike and https://www.facebook.com/nike both work, and duplicates are collapsed before you are charged.

Response fields

Name
pages[].running_ads
Type
boolean
Description
Whether the page has ads live in the Ad Library at the time of the call.
Name
pages[].followers
Type
integer
Description
Followers, which on a Facebook page is a different and usually larger number than likes. Both are returned.
Name
pages_requested
Type
integer
Description
What you asked for and were charged for. A page that is private, renamed or gone comes back missing, so compare it against count.

Request

POST

/v1/social/facebook/page

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/social/facebook/page       -H "Authorization: Bearer $PENGU_API_KEY"       -H "Content-Type: application/json"       -d '{"pages": ["nike", "adidas"]}'

Response

{
  "data": {
    "checked_at": "2026-10-08T10:02:44.106Z",
    "pages_requested": 2,
    "count": 2,
    "pages": [
      {
        "url": "https://www.facebook.com/nike",
        "page_id": "15087023444",
        "name": "Nike",
        "categories": ["Sportswear store"],
        "intro": "Just Do It.",
        "likes": 38200000,
        "followers": 39100000,
        "rating": null,
        "rating_count": null,
        "verified": true,
        "running_ads": true,
        "website": "https://www.nike.com",
        "email": null,
        "phone": null,
        "address": null,
        "messenger": "https://m.me/nike",
        "profile_image_url": "https://scontent.xx.fbcdn.net/...",
        "cover_image_url": "https://scontent.xx.fbcdn.net/...",
        "created_at": "2008-05-14"
      }
    ]
  },
  "meta": {
    "credits_charged": 4,
    "credits_remaining": 2796,
    "request_id": "a31c7f90-55e2-4b18-9d4c-0f2a6e3b1845"
  }
}

POST/v1/social/facebook/search

Search

Search Facebook by keyword. posts returns the public posts and reels that mention the words, ranked by engagement, which is how you hear what people say about a product without following any page. pages returns the pages a niche search turns up, with followers, category, contact details and whether each one is running ads, which is how you build the competitor list that page and ads then go through.

Costs 1.43 credits per result, post or page. 20 results is 28.5 credits.

Required attributes

Name
query
Type
string
Description
Words to search for: a product, a brand or a niche such as dentista madrid.

Optional attributes

Name
type
Type
string
Description
posts or pages. Default posts.
Name
location
Type
string
Description
Free-text country, city or region to narrow the search, for example Spain or Mexico City.
Name
limit
Type
integer
Description
Results to fetch, 5 to 50. Default 20. Capped by your plan.

Response fields

Name
posts[].engagement
Type
integer
Description
Likes plus comments times three plus shares times five. Posts come back sorted by it.
Name
pages[]
Type
array
Description
The same fields as /v1/social/facebook/page, sorted by followers. running_ads on the parent counts how many of them are advertising right now.

Request

POST

/v1/social/facebook/search

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/social/facebook/search \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "protein powder", "type": "posts", "limit": 20}'

Response

{
  "data": {
    "query": "protein powder",
    "type": "posts",
    "location": null,
    "checked_at": "2026-10-16T10:12:40.118Z",
    "count": 20,
    "totals": { "likes": 18420, "comments": 2210, "shares": 640 },
    "posts": [
      {
        "url": "https://www.facebook.com/examplefitness/posts/pfbid0abc123",
        "text": "Tried 6 protein powders for a month. Here is the only one that did not upset my stomach ...",
        "author": "Example Fitness",
        "author_url": "https://www.facebook.com/examplefitness",
        "likes": 4210,
        "comments": 612,
        "shares": 188,
        "engagement": 6986,
        "views": null,
        "type": "image",
        "image_url": "https://scontent.xx.fbcdn.net/v/t39.30808-6/example.jpg",
        "video_url": null,
        "posted_at": "2026-10-09T15:31:00.000Z",
        "hashtags": ["protein", "fitness"]
      }
    ]
  },
  "meta": {
    "credits_charged": 28.5,
    "credits_remaining": 2763.5,
    "request_id": "5b2d1e70-3c4f-4a8e-9d21-7e6f0a1b2c3d"
  }
}