Facebook Ads Search API

Search the Meta Ad Library from your code. One GET request returns the ads that match a keyword or an advertiser, with the text, images, videos, carousel cards, call to action, landing page, platforms and dates of each one, as clean JSON.

Filter by country, status, media type, platform, language and the dates the ads were running, and page through thousands of results with a cursor. No Meta developer account, no identity verification, no scraping to maintain.

No credit card needed. One API key works on every endpoint.

Quick example

GEThttps://api.scrapeadlibrary.com/v1/ads/search
curl "https://api.scrapeadlibrary.com/v1/ads/search?q=running%20shoes&country=US&media_type=video&limit=30" \
  -H "X-API-Key: sal_your_api_key"

Response

{
  "data": [ { "id": "1550534860016399", "page": { "id": "115939511520844", "name": "Perfect themes", ... }, ... } ],
  "total_estimate": 6780,
  "has_more": true,
  "next_cursor": "c_9Xk2a8ZqLw",
  "credits_used": 3,
  "cached": false,
  "media_expires_at": "2026-11-25T18:00:00Z"
}

Illustrative values: a real response carries the live data of the ads and advertisers you ask for.

What each ad contains

Every item of data is an Ad object with a stable shape that does not follow Meta’s internal format, so a change in the Ad Library does not break your parser.

FieldTypeDescription
idstringAd Library ID, also the last part of url.
pageobjectAdvertiser: id, name, categories, like_count, is_person.
statusstringactive or inactive.
started_at / ended_atstring | nullISO 8601 dates the ad started and stopped running.
platformsstring[]facebook, instagram, messenger, audience_network, threads.
formatstringimage, video, carousel, dco, dpa, text or other.
body, title, captionstring | nullAd copy, headline and the domain shown under it.
link_url, ctastring, objectLanding page and call to action (text and type).
images, videos, cardsarrayCreatives with url, preview_url and expires_at; carousel cards.
variants_countintegerHow many versions of the ad Meta grouped together.
politicalobject | nullSpend, impressions, reach and disclaimer of political and issue ads.

The full object, with media and card fields, is in the API reference.

Parameters

ParameterInTypeDefaultDescription
qquerystringrequiredKeyword (1-100 characters). Required unless page_id is given
page_idquerydigits-Restrict the search to one advertiser page
countryquerystringALLISO 3166 alpha-2 country code (e.g. IT, US) or ALL
statusqueryenumactiveactive | inactive | all
ad_typequeryenumallall | political (political and issue ads)
media_typequeryenumallall | image | video | meme | none
platformsquerycsvallAny of facebook, instagram, messenger, audience_network, threads
languagesquerycsvallISO 639-1 language codes (e.g. en,it)
active_fromquerydate-YYYY-MM-DD. With active_to: ads that were running at some point in the window
active_toquerydate-YYYY-MM-DD, end of the window
matchqueryenumanyany | exact (exact phrase)
sortqueryenumrelevancerelevance | impressions (most impressions first)
limitqueryinteger30Ads per page, 1-50
cursorquerystring-next_cursor of the previous page; the other parameters must be identical

Authenticate with the X-API-Key header or Authorization: Bearer. Either q or page_id is required. Results default to active ads in all countries, 30 per page.

What people build with it

Competitor monitoring

Run the same search every day for your competitors’ names and get alerted when a new ad, offer or landing page appears.

Creative research

Collect hooks, formats and calls to action in a niche, filtered by country, platform and media type, to brief your own creatives.

Market intelligence

Count how many advertisers push a product category in each country and how long their ads keep running.

Political ad tracking

With ad_type=political every ad carries spend and impression ranges and the “paid for by” disclaimer.

Pricing

A search costs 1 credit per 10 ads returned, rounded up, so 30 ads cost 3 credits and a search with no results is free. Before fetching, the API lowers limit to what your balance can pay for, so a call never costs more than you have.

  • 100 free credits every month, no credit card
  • Then $1 per 1,000 credits, pay as you go
  • Only successful calls are billed: errors cost nothing
  • Credits never expire; bulk packs from 10,000 credits for $9

See all prices and bulk packs →

Also in the MCP server for AI assistants

The ScrapeAdLibrary MCP server gives Claude, Cursor and other MCP clients the same data as tools: search_ads and get_page_ads. Ask an assistant “which video ads are running shoe brands showing in the US this month?” and it calls the search for you.

Run it with uvx scrapeadlibrary-mcp and your API key in SCRAPEADLIBRARY_API_KEY; the MCP server guide has the configuration for each client. Tool calls are billed like API calls.

Facebook Ads Search API: FAQ

Is there an official Facebook Ad Library API?
Meta offers the ads_archive endpoint of the Graph API, but it needs an identity-verified developer account and returns commercial ads only when they were delivered in the European Union. This API searches the public Ad Library with an API key and no Meta account.
Which ads can I search?
The ads the public Ad Library shows: active ads in every country, every ad delivered in the EU (commercial ones included, kept for a year under the Digital Services Act) and political and issue ads worldwide with spend and impressions.
How do I get more than one page of results?
When has_more is true, send the same request again with cursor set to next_cursor. Cursors last one hour and only work with the parameters of the request that produced them.
How much does a search cost?
1 credit per 10 ads returned, rounded up: a page of 30 ads costs 3 credits and an empty result costs nothing. Every account gets 100 free credits a month.
Can I search the ads of one advertiser?
Yes: pass page_id instead of (or together with) q, or use GET /v1/pages/{page_id}/ads, which takes the same filters.
Do the image and video links last?
No. They point to Meta’s CDN and expire after a few days; every media object has expires_at and the response has media_expires_at, the earliest of them. Download the creatives you want to keep.

Search the Ad Library in minutes

Create a free account, copy your API key and run the example above. 100 free credits every month, no card required.