Return every ad a single advertiser is running, from a page id, an Ad Library advertiser URL, or a facebook.com page URL. Accepts the same filters as a keyword search, plus an optional query to narrow the results within that advertiser's ads.

POST /advertiser-ads Ads

https://api.fetchlayer.dev/facebook-ad-library/advertiser-ads

OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

advertiser string required

Advertiser page id, Ad Library advertiser URL, or facebook.com page URL.

query string optional

Optional keyword to filter within the advertiser's ads.

country string optional

Two-letter country code, or ALL. (default: ALL)

countries string[] optional

Several countries at once (max 20). Overrides country.

activeStatus string optional

active, inactive, or all. (default: active)

adType string optional

ALL or POLITICAL_AND_ISSUE_ADS. (default: ALL)

mediaType string optional

all, image, meme, image_and_meme, video, or none.

publisherPlatforms string[] optional

FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, WHATSAPP, THREADS, OCULUS, UNKNOWN.

contentLanguages string[] optional

Two-letter ad language codes, for example en or es.

bylines string[] optional

Political-ad disclaimers ("paid for by").

startDateFrom string optional

Only ads whose impressions start on or after this YYYY-MM-DD date.

startDateTo string optional

Only ads whose impressions start on or before this YYYY-MM-DD date.

isTargetedCountry boolean optional

Restrict to ads targeting the country rather than merely reaching it.

limit number optional

Maximum ads returned (max 2000), or -1 for everything available. (default: 30)

pages number optional

Pages of results to collect in one request (max 100), or -1 for the maximum allowed.

cursor string optional

Resume from a previous response's nextCursor.

delayMs number optional

Milliseconds to wait between pages (max 30000).

sortBy string optional

start_date, end_date, total_active_time, or none.

sortDirection string optional

asc or desc.

Response Fields

advertiser-ads

Get every ad one advertiser runs

pageId string

The resolved advertiser page id.

pageName string

The advertiser’s page name.

ads object[]

The matching ads, newest data first unless sortBy says otherwise.

ads[].adArchiveId string

Ad Library archive id — the handle for ad-detail and ad-media.

ads[].adLibraryUrl string

Public Ad Library permalink for this ad.

ads[].isActive boolean

Whether the ad was still running when it was scraped.

ads[].startDate string

First day the ad served impressions.

ads[].totalActiveTimeSeconds number

How long the ad has been live — the usual proxy for what is working.

ads[].publisherPlatforms string[]

Surfaces the ad ran on (Facebook, Instagram, Messenger, Threads…).

ads[].advertiser object

Page id, name, URL, categories, like count, and political byline.

ads[].creative object

Title, body, caption, link, CTA, display format, plus videos, images and carousel cards.

ads[].transparency object

Spend, currency, impressions and reach bands for political and issue ads.

adCount number

Number of ads in this response.

pagesScraped number

Pages actually walked. Each page counts as one request against your plan.

nextCursor string

Pass back as cursor to continue from where this response stopped.

hasNextPage boolean

Whether more results are available beyond this response.

Request

curl -X POST "https://api.fetchlayer.dev/facebook-ad-library/advertiser-ads" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"advertiser":"https://www.facebook.com/ads/library/?view_all_page_id=987654321","activeStatus":"active","pages":3}'

Response

{
  "pageId": "987654321",
  "pageName": "Acme Software",
  "adCount": 84,
  "pagesScraped": 3,
  "hasNextPage": false,
  "ads": []
}

{
  "error": "Invalid API key"
}