Facebook Ad Library
Every ad running on Facebook, Instagram, Messenger, Threads, WhatsApp and Audience Network: search by keyword or advertiser, country, ad category, status, media, platform, language and dates; each ad's text, link, images, videos and versions; political ads with spend, impressions, audience and paid-for-by; EU reach; advertiser search and targeting.
/facebook-ad-library/v1/search3 creditsSearch the Ad Library like the site does: by keyword (`query`) and/or advertiser (`page_id`), in one country or ALL, filtered by ad category, active status, media type, platforms, languages and delivery dates, sorted by relevance, newest or fewest impressions. First page up to 30 ads with the source's total; each next_cursor page 10 more. `query` and `page_id` are both optional (empty = every ad matching the filters).
| Parameter | Allowed / range | Description | |
|---|---|---|---|
| query | optional | — | Keyword(s) to search in the ad text, the way the Ad Library search box does. Optional: empty = every ad matching the other filters (e.g. every political ad in a country). |
| page_id | optional | — | Only ads of this Facebook page / advertiser (numeric page id from `advertisers` or from any ad row). Can be combined with `query`. |
| country = ALL | optional | — | Where the ads were delivered: one two-letter ISO country code (US, GB, DE, FR, BR, IN …) or ALL. One country per call. |
| ad_type = all | optional | all · political_and_issue_ads · housing_ads · employment_ads · financial_products_and_services_ads | Ad category, as the Ad Library's 'Ad category' selector. Political and issue ads carry spend, impressions, audience and 'paid for by'. |
| active_status = active | optional | active · inactive · all | Whether the ad is still running. |
| media_type = all | optional | all · image · video · meme · image_and_meme · none | Creative media type. |
| search_type = keyword_unordered | optional | keyword_unordered · keyword_exact_phrase | How `query` is matched. Exact phrase only narrows multi-word queries. |
| platforms | optional | facebook · instagram · messenger · audience_network · threads · whatsapp | Only ads shown on these platforms (one or several, comma-separated): facebook, instagram, messenger, audience_network, threads, whatsapp. |
| languages | optional | — | Only ads in these languages (ISO 639-1 codes, comma-separated: en, es, de …). |
| start_date | optional | — | Ads that were running on or after this date (YYYY-MM-DD). This is the delivery window, not the ad's creation date. |
| end_date | optional | — | Ads that were running on or before this date (YYYY-MM-DD). |
| sort = relevance | optional | relevance · newest · impressions_asc | Result order. For political / issue ads the default (relevance) order is already most-impressions-first; impressions_asc reverses it. It does not reorder commercial ads (they publish no impressions). |
| cursor | optional | — | next_cursor from the previous search page. It carries that search's filters, so pass it alone. |
/facebook-ad-library/v1/ad3 creditsOne ad by its Ad Library id: the full ad card (same fields as search) plus the transparency details — advertiser page (name, category, likes, Instagram account and followers, verification, about text), page spend by disclaimer, political insights (age × gender share, reach by region), EU transparency (targeted countries, age, gender, EU reach and reach by country × age × gender), payer and beneficiary, financial-services licensing.
| Parameter | Allowed / range | Description | |
|---|---|---|---|
| ad_archive_id | required | — | Ad Library id of the ad (`ad_archive_id` from search; an Ad Library URL …/ads/library/?id=… is accepted too). |
| country = ALL | optional | — | Country for the transparency details (two-letter code or ALL). EU countries return EU reach and audience; the political insights follow the ad's own country. |
/facebook-ad-library/v1/variations1 creditEvery version of a collated ad (the 'N ads use this creative and text' group): one ad row per version, same fields as search.
| Parameter | Allowed / range | Description | |
|---|---|---|---|
| collation_id | required | — | collation_id of an ad row whose collation_count is 2 or more. |
| country = ALL | optional | — | Country filter for the versions (two-letter code or ALL). |
| active_status = all | optional | active · inactive · all | Whether the version is running. |
| cursor | optional | — | next_cursor from the previous variations page. |
/facebook-ad-library/v1/advertisers1 creditFind advertisers (Facebook pages) by name, the way the Ad Library search box suggests them: page id, name, category, likes, Instagram username / followers / verification, verification badge, country. Use page_id with search / advertiser_targeting.
| Parameter | Allowed / range | Description | |
|---|---|---|---|
| query | required | — | Advertiser / page name to look up, as typed into the Ad Library search box. |
| country = ALL | optional | — | Country (two-letter code or ALL). |
| ad_type = all | optional | all · political_and_issue_ads | Restrict to advertisers of political / issue ads. |
/facebook-ad-library/v1/advertiser_targeting1 creditHow a page targets its political / social-issue ads over the last 7, 30 or 90 days, as the Ad Library 'Audience' tab shows it: total spend, number of ads, and spend share by location, age, gender, language, detailed targeting, custom and lookalike audiences. Pages with no such ads return empty lists.
| Parameter | Allowed / range | Description | |
|---|---|---|---|
| page_id | required | — | Numeric Facebook page id. |
| days = 30 | optional | 7 · 30 · 90 | Reporting window. |
curl -X POST https://api.reefapi.com/facebook-ad-library/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"nike","country":"US"}'{
"ok": true,
"data": { /* the result */ },
"meta": {
"latency_ms": 240,
"record_count": 12,
"completeness_pct": 100
},
"error": null
}Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.
Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.
Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.
No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.
Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.