Facebook and InstagramKeyword or pageEU reachSandbox
Meta Ad Library API
Search the Meta Ad Library from your own software. Send a keyword or a Facebook page id and get up to 30 ads a page as JSON: text, media, dates and placements.
- Sandbox key straight away
- 100 credits a month free
- No card
GET /v1/meta/ads?q=running+shoes&country=GB&active=true
authorization: Bearer $PADS_API_KEY
Northwind Running Co
Trail shoes, half price this week
Grip that holds on wet rock. Free returns for 60 days.
- Shown
- 4 Aug 2026 to 18 Oct 2026
- Where
- Facebook, Instagram, Audience network, Messenger
meta_900000000000001In the libraryWhat you can search
Search the Meta Ad Library
GET /v1/meta/ads takes one of two subjects and the filters this library has. A filter it doesn’t have is refused by name, so nothing is silently ignored.
A keyword
q finds ads with those words. Set exact=true to match a phrase.
One advertiser
page_id returns one Facebook page’s ads. Take it from any result’s advertiser.id.
q- Values
- Words in the ad. Set exact to match it as a phrase.
- Default
- One subject is required
page_id- Values
- One advertiser’s Facebook page id, from a search result’s advertiser.id.
- Default
- One subject is required
country- Values
- ISO 3166 alpha-2, or ALL
- Default
- ALL
active- Values
- true, false
- Default
- Both
format- Values
- image, video, meme, none
- Default
- All
placements- Values
- Comma separated: facebook, instagram, messenger, audience_network, threads
- Default
- All
category- Values
- all, political_and_issue, housing, employment, financial
- Default
- all
language- Values
- ISO 639-1
- Default
- All
sort- Values
- impressions, newest
- Default
- impressions
exact- Values
- true, false
- Default
- false
date_from- Values
- YYYY-MM-DD
- Default
- Any
date_to- Values
- YYYY-MM-DD
- Default
- Any
cursor- Values
- next_cursor from the last page, with the same parameters
- Default
- First page
One ad
What one ad’s detail adds
GET /v1/ads/{id} returns the ad with everything the Meta Ad Library shows about it, in one call, for 1 credit.
- For ads delivered in the EU: total EU reach, and reach by country, age and gender.
- For the same ads: the locations, ages and genders targeted, and who paid and who benefits.
- For political and issue ads anywhere: spend and impressions ranges.
- Every variant of the ad, with its text and media.
GET https://api.publicadsapi.com/v1/ads/meta_900000000000001
Where the library is thin
Meta shows US ads only while they run. A stopped US ad stays in the library only if it is a political or issue ad, for 7 years; EU and UK ads stay for a year after they stop. Reach and targeting come only for ads delivered in the EU. These limits are the library’s, so they bind every API that reads it.
ScrapeCreators, Adyntel, SearchAPI and several Apify scrapers also search the Meta Ad Library. Foreplay serves Meta ads from its own stored index rather than the live library.
Sandbox
Every answer, before your first live search
Your sandbox key comes the moment you sign up. Any search returns sample ads from made-up advertisers in the live shape, and these searches return what a live one can. None of them uses a credit.
200, no ads
q=emptyA search that finds nothing. An empty page uses no credits.
503 UPSTREAM_BLOCKED
q=blockedThe platform refused every address we tried. Retry-After says when to try again.
504 TIMEOUT
q=timeoutThe platform didn’t answer in time. Retry, or narrow the search.
502 UPSTREAM_CHANGED
q=changedThe platform’s page changed and we couldn’t read it. We are alerted.
1 credit
a page of ads, or one ad
Up to 30 ads a page. 100 credits a month free, no card.
$0.065
per 1,000 ads on Growth
With full pages: $49 a month for 25,000 credits.
$0
when there is nothing
Empty pages, blocks, timeouts and errors use no credits.
Ask your AI about this API
It reads this page, then tells you if it fits, what it costs and what building it takes.
Questions
Before you build
Is there an official Meta Ad Library API?
Yes, but it is narrow. Meta’s ads_archive endpoint needs a confirmed identity, returns ads outside the EU and UK only when they are political or issue ads, and gives no media URLs. Public Ads API reads the public Ad Library page instead, so commercial ads anywhere come back with their images and videos.
What does a Meta search cost?
A page of up to 30 ads uses 1 credit, and so does one ad with all its detail. On Growth ($49 for 25,000 credits) that is about $0.065 per 1,000 ads with full pages. An empty page, a block, an error and every sandbox call use nothing. The free plan has 100 credits a month and needs no card.
Can I get one advertiser’s ads?
Yes. Search once by keyword, take the advertiser.id of the ad you want, and send it as page_id. Every ad that Facebook page runs comes back, 30 a page, with next_cursor for the next page.
Do you charge for a search with no ads?
No. An empty page uses no credits. Meta sometimes answers a blocked request with an empty page, so before we answer empty we check the same address still finds ads for a query that always has them. A blocked search is retried on new addresses, and is free if every try fails.
How long do media URLs last?
Meta’s image and video addresses expire, often within days. Download what you want to keep when you get it. We don’t host copies.
Your first Meta Ad Library search,
in the next ten minutes
Sandbox key straight away. 100 credits a month free.