The Meta Ad Library API lets you run custom searches of Meta's Ad Library through code. It covers ads about social issues, elections or politics delivered anywhere in the world in the past 7 years, and ads of any type delivered to the UK or European Union in the past year. To use it you confirm your identity at Facebook.com/ID, create a Meta for Developers account and add an app.
That scope is the part people miss. The API isn't a back door to every ad running on Facebook and Instagram. For ordinary commercial ads shown only outside the UK and EU, Meta points you to the regular Ad Library search instead.
What the Ad Library API covers
| Ad type | Where it ran | How far back |
|---|---|---|
| Ads about social issues, elections or politics | Anywhere in the world | The past 7 years |
| Ads of any type | Delivered to the UK or the European Union | The past year |
| Other commercial ads | Outside the UK and EU only | Not in the API; use the Ad Library website |
Meta's own note on the country parameter says it plainly: ads that didn't reach any location in the EU only come back if they're about social issues, elections or politics.
How to get access, in 3 steps
- Confirm your identity and location. Go to Facebook.com/ID and complete the confirmation process used for running ads about social issues, elections or politics. Meta says this can take a few days.
- Create a Meta for Developers account. Select Get started and agree to Meta's Platform Policy.
- Add a new app. Return to the Ad Library API page, select Access the API, then create an app from My Apps and Create App.
You'll need a Facebook account to get authorised. Meta also suggests some familiarity with programming, and recommends the Ad Library Report as a simpler option if you don't code. Experienced developers can use Meta's Ad Library API script repository on GitHub, which includes code examples and a simple command-line interface.
What every result includes
Every available ad in the API comes with the same basics:
- The Library ID.
- The content of the ad creative, subject to Meta's Terms of Service.
- The Page name and Page ID behind the ad.
- Ad delivery dates.
- Where the ad appeared, such as Facebook or Instagram.
Extra data by ad type
| Field | Political and issue ads | Ads delivered to the UK and EU |
|---|---|---|
| Amount spent | Yes, as a range, in the currency the advertiser paid in | No |
| Impressions | Yes, as a range | Estimated total impressions in the UK and EU |
| Demographics of reach | Age, gender and location breakdown | UK and EU targeting and reach demographics, estimated |
| Who paid | The paid-for-by byline | Advertiser and payer information, EU only |
| Targeting settings | For ads delivered to Brazil | Target ages, gender and locations |
Spend is reported in bands, not exact figures: under 100, 100 to 499, 500 to 999, then wider bands up to over 1M. Impressions also come in bands, starting at under 1,000. If you need exact spend for a competitor's ads, the API won't give it to you.
Search parameters worth knowing
| Parameter | What it does |
|---|---|
| ad_reached_countries | Required. Search ALL or by ISO country code |
| ad_type | ALL, or one special category: political and issue, employment, housing, or financial products and services |
| ad_active_status | ACTIVE by default; INACTIVE or ALL to include ads no longer running |
| search_terms | Up to 100 characters; a space works as AND |
| search_type | Keywords in any order, or an exact phrase |
| search_page_ids | Up to ten Facebook Page IDs at once |
| publisher_platforms | Facebook, Instagram, Audience Network, Messenger, WhatsApp, Threads and more |
| media_type | Image, meme, video, none or all |
| languages | Ads in specific languages, using ISO language codes |
Two details save debugging time. The default status is ACTIVE, so a search for an advertiser's past campaigns returns nothing until you switch it to ALL or INACTIVE. And the financial products and services type now replaces the old credit ads type; Meta says queries using the old name return the new data.
Using the data responsibly
Meta notes you can't download a batch of archived ads, though you can download the creative for an individual ad for analysis, as long as you follow the data storage terms in its Terms of Service. Ad creation time also isn't the same as when the ad ran, so use the delivery start and stop times for timelines. For what you can and can't fairly take from a rival's ads, see what you can legally learn from competitor marketing.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
My verdict
If you research political advertising or work with UK and EU campaigns, the Ad Library API gives you far more structured data than the website, and the 3-step access process is worth a few days' wait. If you just want to see what a competitor is running in the US, skip the API: the Ad Library website shows you that without code, and paid tools fill other gaps, as covered in my roundup of AdSpy alternatives.
Frequently asked questions
What does the Meta Ad Library API include?
Ads about social issues, elections or politics delivered anywhere in the world in the past 7 years, and ads of any type delivered to the UK or European Union in the past year.
How do I get access to the Ad Library API?
Confirm your identity and location at Facebook.com/ID, create a Meta for Developers account, then return to the Ad Library API page, select Access the API and create an app.
Can the Ad Library API show how much a competitor spends?
Only for ads about social issues, elections or politics, and only as a range such as 100 to 499. Other ads don't include spend.
Does the Ad Library API include US commercial ads?
Only if they're about social issues, elections or politics, or were also delivered to the UK or EU. Meta says ads that didn't reach any location in the EU only come back if they're political or issue ads.
Do I need to code to use the Ad Library API?
Meta says it helps to be a little familiar with programming. For a simpler option it suggests the Ad Library Report, and for current ads it points to the Ad Library itself.
