Skip to content
truescrape
Free key

Contents

Site

Facebook Page Ads API

Open in ChatGPTOpen in ClaudeOpen in Gemini

Ads a specific Facebook page is running or has run, from Meta's Ad Library. This is the competitor-monitoring endpoint. pagination.cursor is filled only where the deployment reads the Graph Ad Library API; otherwise pagination.hasMore says whether more exist. Calls cost 2 credits each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/facebook/ad-library/page-ads
ParameterTypeRequiredDescription
page_idstringyesNumeric page id, or an Ad Library URL containing view_all_page_id
countrystringnoISO-3166 country code(s) the ad reached, comma-separated. Meta requires at least one.defaults to US
statusactive | inactive | allnoDelivery status at the time of the query.defaults to active
ad_typeall | political | housing | employment | creditnopolitical unlocks Meta's spend, impression and demographic fields.defaults to all
media_typeall | image | meme | video | noneno—
platformstringnoComma-separated: facebook, instagram, messenger, audience_network, threads, whatsapp, oculus
languagestringnoComma-separated BCP-47 codes, e.g. "en,es"
start_datestringnoEarliest delivery date, YYYY-MM-DD
end_datestringnoLatest delivery date, YYYY-MM-DD
limitnumbernoAds per page, 1-100. Default 25.
cursorstringnopagination.cursor from a previous response
pageIdstringnoNumeric page id, or an Ad Library URL containing view_all_page_id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/page-ads?page_id=15087023444&cache_max_age=7d" \
  -H "x-api-key: $KEY"
JavaScript
const query = new URLSearchParams({
  page_id: '15087023444',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/page-ads?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 2 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/page-ads",
    params={
        "page_id": "15087023444",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on , with raw removed and lists cut to two items. A live call returns current data.

response
{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "facebook",
        "id": "1016451784037642",
        "advertiserId": "15087023444",
        "advertiserName": "Nike",
        "url": "https://www.facebook.com/ads/library/?id=1016451784037642",
        "headline": "Nike Air Monarch IV ",
        "body": "Get the gear that goes hard on and off the field.",
        "ctaText": "Shop now",
        "linkUrl": "https://www.nike.com/us/en_us",
        "creativeType": "dpa",
        "imageUrls": [
          "https://scontent-cdg4-3.xx.fbcdn.net/v/t39.35426-6/509094198_1485897442775736_2519419118144931021_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=k43RoQU6bK0Q7kNvwEmow6_&_nc_oc=Adp8_RGVMeMMZABUnpa0oHVJsnvbfg5Qb2bKErbXmS148rKhoGXvJaRrVIhPnyBJxYs&_nc_zt=14&_nc_ht=scontent-cdg4-3.xx&_nc_gid=5hcISibrVGuEDqG6gEAUHw&_nc_ss=7b289&oh=00_AQMb7QUAWuMH3hP_3k5E7_fGzMvLsJGVv0JHfft1LNVaGQ&oe=6ADDFE35",
          "https://scontent-cdg4-2.xx.fbcdn.net/v/t39.35426-6/508595289_3894423190809901_7283310637062104285_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=2BbPvBAgr_4Q7kNvwFuTtNs&_nc_oc=AdozFhkGI73F0cyEkKkBKximojRIQWJHuTUWZk7siUEut-_dWYSTzflCj_W2CAlWDlQ&_nc_zt=14&_nc_ht=scontent-cdg4-2.xx&_nc_gid=5hcISibrVGuEDqG6gEAUHw&_nc_ss=7b289&oh=00_AQNksGPhsceowL8vK31HjirDmx6E2XTC3XDCD7Swn_pcwQ&oe=6ADDDB87"
        ],
        "videoUrls": [],
        "platforms": [
          "facebook",
          "instagram"
        ],
        "countries": [
          "US"
        ],
        "languages": [],
        "startedAt": "2025-06-20T07:00:00.000Z",
        "endedAt": null,
        "isActive": true,
        "impressionsLower": null,
        "impressionsUpper": null,
        "spendLower": null,
        "spendUpper": null,
        "currency": null,
        "fetchedAt": "2026-10-21T01:51:24.892Z"
      },
      {
        "platform": "facebook",
        "id": "1277433457899494",
        "advertiserId": "15087023444",
        "advertiserName": "Nike",
        "url": "https://www.facebook.com/ads/library/?id=1277433457899494",
        "headline": "Nike Air Monarch IV ",
        "body": "Run through summer with gear that can take the heat.",
        "ctaText": "Shop now",
        "linkUrl": "https://www.nike.com/",
        "creativeType": "dpa",
        "imageUrls": [
          "https://scontent-cdg6-1.xx.fbcdn.net/v/t39.35426-6/787341597_1403139668417555_3205388062094203287_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=cufseGe87VsQ7kNvwEE27MA&_nc_oc=Adolu5UHrn1dX_RERy-R_N7YnesKZcYpPKoxUxv5J1KdnaatVgVhD27NGMABUEL8vRc&_nc_zt=14&_nc_ht=scontent-cdg6-1.xx&_nc_gid=5hcISibrVGuEDqG6gEAUHw&_nc_ss=7b289&oh=00_AQNI8my-Xe1rsBl_Mwskwuv1oKf7Np5kcrUnrv0EA8KEvA&oe=6ADDF62A",
          "https://scontent-cdg4-2.xx.fbcdn.net/v/t39.35426-6/787818083_1363817722503117_346426616878533322_n.jpg?_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=pulFUk3r770Q7kNvwG-cMSm&_nc_oc=AdprQc3CIuz1TCoXeIZ1jFUkW-D3I00Q0WlDdnY9lqeUqX0ALMtmyPG-dyEl3EmnoQU&_nc_zt=14&_nc_ht=scontent-cdg4-2.xx&_nc_gid=5hcISibrVGuEDqG6gEAUHw&_nc_ss=7b289&oh=00_AQN-JMUYnvlNm-7rU9fKsSezejtR3y6ZyQ6b4hXchbDu3w&oe=6ADDDC9A"
        ],
        "videoUrls": [],
        "platforms": [
          "facebook",
          "instagram"
        ],
        "countries": [
          "US"
        ],
        "languages": [],
        "startedAt": "2026-10-19T07:00:00.000Z",
        "endedAt": null,
        "isActive": true,
        "impressionsLower": null,
        "impressionsUpper": null,
        "spendLower": null,
        "spendUpper": null,
        "currency": null,
        "fetchedAt": "2026-10-21T01:51:24.892Z"
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": true,
    "count": 25
  },
  "meta": {
    "platform": "facebook",
    "endpoint": "facebook.pageAds",
    "creditsCharged": 2,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 9983,
    "requestId": "req_9z48idw4ldqg2ib01jhf"
  }
}

Returns

Returns a list of Ad in data.items.

Cost and behaviour

Credits2 per live request, 0 on a cache hit
Cacheableyes: cache_max_age accepts a cached copy
Batchableyes: usable as a target in POST /v1/jobs/batch
Subscribableyes: as often as every 3600 seconds, firing a webhook only on a change

Other Facebook endpoints

All Facebook endpointsThe unified schema