Facebook Ad Library Search API

Open in ChatGPT Open in Claude Open in Gemini

Facebook, Instagram, Messenger and Threads ads matching a search term, from Meta's Ad Library, in the Library's own order. Spend and impression ranges are filled for political and issue ads only where the deployment reads the Graph Ad Library API; pagination.hasMore says when more results 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/search

Parameter Type Required Description

query string yes Search term, matched against ad text and advertiser name

search_type unordered | exact_phrase no exact_phrase matches the words in orderdefaults to unordered

country string no ISO-3166 country code(s) the ad reached, comma-separated. Meta requires at least one.defaults to US

status active | inactive | all no Delivery status at the time of the query.defaults to active

ad_type all | political | housing | employment | credit no political unlocks Meta's spend, impression and demographic fields.defaults to all

media_type all | image | meme | video | none no —

platform string no Comma-separated: facebook, instagram, messenger, audience_network, threads, whatsapp, oculus

language string no Comma-separated BCP-47 codes, e.g. "en,es"

start_date string no Earliest delivery date, YYYY-MM-DD

end_date string no Latest delivery date, YYYY-MM-DD

limit number no Ads per page, 1-100. Default 25.

cursor string no pagination.cursor from a previous response

Parameter	Type	Required	Description
query	string	yes	Search term, matched against ad text and advertiser name
search_type	unordered \| exact_phrase	no	`exact_phrase` matches the words in orderdefaults to unordered
country	string	no	ISO-3166 country code(s) the ad reached, comma-separated. Meta requires at least one.defaults to US
status	active \| inactive \| all	no	Delivery status at the time of the query.defaults to active
ad_type	all \| political \| housing \| employment \| credit	no	`political` unlocks Meta's spend, impression and demographic fields.defaults to all
media_type	all \| image \| meme \| video \| none	no	—
platform	string	no	Comma-separated: facebook, instagram, messenger, audience_network, threads, whatsapp, oculus
language	string	no	Comma-separated BCP-47 codes, e.g. "en,es"
start_date	string	no	Earliest delivery date, YYYY-MM-DD
end_date	string	no	Latest delivery date, YYYY-MM-DD
limit	number	no	Ads per page, 1-100. Default 25.
cursor	string	no	`pagination.cursor` from a previous response

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/search?query=nike&cache_max_age=7d" \
  -H "x-api-key: $KEY"

JavaScript

const query = new URLSearchParams({
  query: 'nike',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/search?${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/search",
    params={
        "query": "nike",
        "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 2026-10-21, with raw removed and lists cut to two items. A live call returns current data.

response

{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "facebook",
        "id": "1550534860016399",
        "advertiserId": "115939511520844",
        "advertiserName": "Perfect themes",
        "url": "https://www.facebook.com/ads/library/?id=1550534860016399",
        "headline": "𝕊𝕦𝕡𝕖𝕣 𝕙𝕠𝕥 𝕨𝕚𝕕𝕘𝕖𝕥𝕤 𝕒𝕡𝕡 ！",
        "body": "🔥🍭Themepack is a FREE and personalized APP😍 various styles of Theme💎 、Weather💖、Photo😊、Clock、Calendar to pick any widget to dress up your home screen！",
        "ctaText": "Install now",
        "linkUrl": "http://play.google.com/store/apps/details?id=com.iconchanger.widget.theme.shortcut",
        "creativeType": "image",
        "imageUrls": [
          "https://scontent-man2-1.xx.fbcdn.net/v/t39.35426-6/700927950_933331229664450_6487763311056032772_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Imwm7ncZuIwQ7kNvwGS96IO&_nc_oc=Adre0UymHG9gLxa1nsRcI0rSHSVLtOYtwK67g-dC7eSKksDN1e4P99Fws7sivZb-Ohw&_nc_zt=14&_nc_ht=scontent-man2-1.xx&_nc_gid=imkpUV_2J4y5YLsEzuTqew&_nc_ss=79289&oh=00_AQMW7eZOgxkIv3HuAysrMtQO8FvoMHJB7KCM-a24QlaiFA&oe=6ADDDCFA"
        ],
        "videoUrls": [],
        "platforms": [
          "facebook",
          "instagram"
        ],
        "countries": [
          "US"
        ],
        "languages": [],
        "startedAt": "2026-05-19T07:00:00.000Z",
        "endedAt": null,
        "isActive": true,
        "impressionsLower": null,
        "impressionsUpper": null,
        "spendLower": null,
        "spendUpper": null,
        "currency": null,
        "fetchedAt": "2026-10-21T01:51:37.418Z"
      },
      {
        "platform": "facebook",
        "id": "962050096457659",
        "advertiserId": "156405867784232",
        "advertiserName": "Depop",
        "url": "https://www.facebook.com/ads/library/?id=962050096457659",
        "headline": "LOFT Women's Blouse",
        "body": "Free Depop Shipping just dropped. Go find something you love.",
        "ctaText": "Download",
        "linkUrl": "http://itunes.apple.com/app/id518684914",
        "creativeType": "dpa",
        "imageUrls": [
          "https://scontent-man2-1.xx.fbcdn.net/v/t39.35426-6/706277043_1509973367377594_8218495971134332071_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=slihMuflq0wQ7kNvwFDoGg8&_nc_oc=AdorKB74JeT6162Q_Qc8JWFAl5TRojXd1ZSNs4zXYPV8H7JVaUmdB6NijTHLv8UzAJY&_nc_zt=14&_nc_ht=scontent-man2-1.xx&_nc_gid=imkpUV_2J4y5YLsEzuTqew&_nc_ss=79289&oh=00_AQMUAPJRIpAsqhFH3hSIsXfHcFCDau5lOjxUs-kppFR1tQ&oe=6ADDF68E",
          "https://scontent-man2-1.xx.fbcdn.net/v/t39.35426-6/706198623_1758809891778866_1474232210027622534_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=k6XRMM6omBAQ7kNvwH_xYUP&_nc_oc=Adp0I0NmYEY8bRCJQeziKfiAU5Sfiv6gt7Cg2PmBijBQdXab3OwftTPyh8zIC1Y6fFE&_nc_zt=14&_nc_ht=scontent-man2-1.xx&_nc_gid=imkpUV_2J4y5YLsEzuTqew&_nc_ss=79289&oh=00_AQMxf1Cx5NplYGUGe2EimOuWMXzLlUB08vglzzOi2lNSMw&oe=6ADE08B7"
        ],
        "videoUrls": [],
        "platforms": [
          "facebook",
          "instagram"
        ],
        "countries": [
          "US"
        ],
        "languages": [],
        "startedAt": "2026-05-22T07:00:00.000Z",
        "endedAt": null,
        "isActive": true,
        "impressionsLower": null,
        "impressionsUpper": null,
        "spendLower": null,
        "spendUpper": null,
        "currency": null,
        "fetchedAt": "2026-10-21T01:51:37.418Z"
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": true,
    "count": 25
  },
  "meta": {
    "platform": "facebook",
    "endpoint": "facebook.adLibrarySearch",
    "creditsCharged": 2,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 12134,
    "requestId": "req_s8s2n0gzavv1mzoi44fz"
  }
}

Returns

Returns a list of Ad in data.items.

Cost and behaviour

Credits

2 per live request, 0 on a cache hit

Cacheable

yes: cache_max_age accepts a cached copy

Batchable

yes: usable as a target in POST /v1/jobs/batch

Subscribable

yes: as often as every 3600 seconds, firing a webhook only on a change

Other Facebook endpoints

/v1/facebook/ad-library/ad Ad details
/v1/facebook/ad-library/ad-transcript Ad video transcript
/v1/facebook/ad-library/advertisers Find advertisers running ads
/v1/facebook/ad-library/page-ads All ads for one advertiser
/v1/facebook/city-events Get the events of a city
/v1/facebook/comment-replies Replies to a comment
/v1/facebook/event Event details
/v1/facebook/events/search Search public events

All Facebook endpoints The unified schema

Contents

Site