M
MesmerTools
GET/v1/facebook/adLibrary/company/ads

Company ads API

Lists every public ad running (or previously run) by a single advertiser Page. Supply `pageId` if you have it; if you only have a name, supply `companyName` and we'll resolve via typeahead first. Top-level response uses `results` (not `searchResults`).

Authentication

Include x-api-key: <your_key> in your request headers
Requests without a valid key get a 401 Unauthorized. Revoked keys return 403 Forbidden.
Get a key

Parameters

pageIdEither/Or
string
Facebook Page id. Preferred when known.
companyNameEither/Or
string
Page name to resolve via typeahead. First match wins.
countryOptional
stringdefault: ALL
2-letter ISO code or "ALL".
statusOptional
enumdefault: all
Active status filter.
allactiveinactive
media_typeOptional
enumdefault: all
Creative format filter.
allimagevideomeme
languageOptional
string
ISO language hint (FB ignores this for many countries — included for parity).
sort_byOptional
string
Facebook's ordering hint. Leave empty for default.
start_dateOptional
string
YYYY-MM-DD lower bound.
end_dateOptional
string
YYYY-MM-DD upper bound.
cursorOptional
string
Pagination cursor.
trimOptional
boolean
Drop snapshot.images/videos/cards.
You must supply one of pageId or companyName.

Example request

curl "https://mesmer.tools/api/v1/facebook/adLibrary/company/ads?companyName=Notion&country=US" \
  -H "x-api-key: <YOUR_API_KEY>"

Try it now

Hits the live endpoint with your API key.

Saved locally in your browser. Mint a key in /admin/api-keys.

Response schema

Trimmed example — see Field reference for descriptions.

{
  "success": true,
  "credits_remaining": -1,
  "searchResultsCount": 312,
  "cursor": "AQHRl4y7v...",
  "results": [
    {
      "ad_archive_id": "1234567890123456",
      "page_id": "232540286768801",
      "page_name": "Notion",
      "is_active": true,
      "start_date": 1775520000,
      "start_date_string": "2026-04-04",
      "end_date": null,
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "snapshot": {
        "body": {
          "text": "Meet Notion AI — your second brain..."
        },
        "page_name": "Notion",
        "cta_text": "Try for free",
        "link_url": "https://www.notion.so/product/ai"
      },
      "url": "https://www.facebook.com/ads/library/?id=1234567890123456"
    },
    "...29 more ads"
  ]
}

Field reference

Each results[] entry — the fields you'll most likely use.

ad_archive_id
string
Stable Ad Library archive id. Use this with /v1/facebook/adLibrary/ad for detail lookups.
page_id
string
Facebook Page id of the advertiser.
page_name
string
Display name of the advertising Page.
is_active
boolean
Whether the ad is currently running.
start_date
number
Run-start time as Unix epoch seconds (null if unknown).
end_date
number
Run-end time as Unix epoch seconds (null if still active).
publisher_platform
string[]
Surfaces the ad ran on, e.g. ["FACEBOOK", "INSTAGRAM"].
snapshot
object
Creative payload — body text, images, videos, cta, link, page_profile_picture_url.
currency
string
Currency code of any disclosed spend bucket.
url
string
Public Ad Library URL for this archive id.
Previous
Search ads
/v1/facebook/adLibrary/search/ads
Next
Ad detail
/v1/facebook/adLibrary/ad