> Search the Meta Ad Library by keyword or Facebook page from your code. Up to 30 ads a page as JSON, EU reach in one call, 1 credit a page. Web version: https://publicadsapi.com/meta-ad-library-api · Last updated: 2026-10-21 # 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. [Read the quickstart](https://publicadsapi.com/docs/quickstart) - Sandbox key straight away - 100 credits a month free - No card What 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. Parameters of GET /v1/meta/ads | Parameter | Values | Default | | --- | --- | --- | | `q` | Words in the ad. Set exact to match it as a phrase. | One subject is required | | `page_id` | One advertiser’s Facebook page id, from a search result’s advertiser.id. | One subject is required | | `country` | ISO 3166 alpha-2, or ALL | ALL | | `active` | true, false | Both | | `format` | image, video, meme, none | All | | `placements` | Comma separated: facebook, instagram, messenger, audience\_network, threads | All | | `category` | all, political\_and\_issue, housing, employment, financial | all | | `language` | ISO 639-1 | All | | `sort` | impressions, newest | impressions | | `exact` | true, false | false | | `date_from` | YYYY-MM-DD | Any | | `date_to` | YYYY-MM-DD | Any | | `cursor` | next\_cursor from the last page, with the same parameters | 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. [Read the quickstart](https://publicadsapi.com/docs/quickstart) - 200, no ads `q=empty` A search that finds nothing. An empty page uses no credits. - 503 UPSTREAM\_BLOCKED `q=blocked` The platform refused every address we tried. Retry-After says when to try again. - 504 TIMEOUT `q=timeout` The platform didn’t answer in time. Retry, or narrow the search. - 502 UPSTREAM\_CHANGED `q=changed` The 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. [See pricing](https://publicadsapi.com/pricing) 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. [Read the quickstart](https://publicadsapi.com/docs/quickstart)