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

Search ads API

Keyword-based search across every public ad in the Facebook Ad Library. Supports filters by country, status, ad type, media type, and date range. Paginates via the opaque `cursor` value in the response.

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

queryRequired
string
Search string — keyword(s) to match against ad copy.
sort_byOptional
string
Facebook's ordering hint. Leave empty for default.
search_typeOptional
enumdefault: keyword_unordered
How `query` is interpreted.
keyword_unorderedkeyword_exact_phrase
ad_typeOptional
enumdefault: ALL
Ad type filter.
ALLPOLITICAL_AND_ISSUE_ADSEMPLOYMENT_ADSHOUSING_ADSCREDIT_ADS
countryOptional
stringdefault: ALL
2-letter ISO country code, or "ALL".
statusOptional
enumdefault: all
Active status filter.
allactiveinactive
media_typeOptional
enumdefault: all
Creative format filter.
allimagevideomeme
start_dateOptional
string
YYYY-MM-DD lower bound on first-shown date.
end_dateOptional
string
YYYY-MM-DD upper bound on last-shown date.
cursorOptional
string
Pagination cursor — pass the previous response's `cursor`.
trimOptional
boolean
Set to "true" to drop snapshot.images/videos/cards arrays (faster, smaller).

Example request

curl "https://mesmer.tools/api/v1/facebook/adLibrary/search/ads?query=AI+agent&country=US&status=active" \
  -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": 12480,
  "cursor": "AQHRl4y7v...",
  "searchResults": [
    {
      "ad_archive_id": "1234567890123456",
      "ad_id": null,
      "page_id": "232540286768801",
      "page_name": "Notion",
      "is_active": true,
      "start_date": 1775520000,
      "start_date_string": "2026-04-04",
      "end_date": null,
      "end_date_string": null,
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "snapshot": {
        "body": {
          "text": "Meet Notion AI — your second brain..."
        },
        "page_name": "Notion",
        "page_profile_picture_url": "https://...jpg",
        "cta_text": "Try for free",
        "link_url": "https://www.notion.so/product/ai",
        "images": [
          "...trimmed..."
        ],
        "videos": [],
        "cards": []
      },
      "currency": "",
      "url": "https://www.facebook.com/ads/library/?id=1234567890123456"
    },
    "...29 more ads"
  ]
}

Field reference

Each searchResults[] 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 companies
/v1/facebook/adLibrary/search/companies
Next
Company ads
/v1/facebook/adLibrary/company/ads