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
https://api.scrapeadlibrary.com/v1/ads/searchcurl "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.
| Field | Type | Description |
|---|---|---|
| id | string | Ad Library ID, also the last part of url. |
| page | object | Advertiser: id, name, categories, like_count, is_person. |
| status | string | active or inactive. |
| started_at / ended_at | string | null | ISO 8601 dates the ad started and stopped running. |
| platforms | string[] | facebook, instagram, messenger, audience_network, threads. |
| format | string | image, video, carousel, dco, dpa, text or other. |
| body, title, caption | string | null | Ad copy, headline and the domain shown under it. |
| link_url, cta | string, object | Landing page and call to action (text and type). |
| images, videos, cards | array | Creatives with url, preview_url and expires_at; carousel cards. |
| variants_count | integer | How many versions of the ad Meta grouped together. |
| political | object | null | Spend, impressions, reach and disclaimer of political and issue ads. |
The full object, with media and card fields, is in the API reference.
Parameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
| q | query | string | required | Keyword (1-100 characters). Required unless page_id is given |
| page_id | query | digits | - | Restrict the search to one advertiser page |
| country | query | string | ALL | ISO 3166 alpha-2 country code (e.g. IT, US) or ALL |
| status | query | enum | active | active | inactive | all |
| ad_type | query | enum | all | all | political (political and issue ads) |
| media_type | query | enum | all | all | image | video | meme | none |
| platforms | query | csv | all | Any of facebook, instagram, messenger, audience_network, threads |
| languages | query | csv | all | ISO 639-1 language codes (e.g. en,it) |
| active_from | query | date | - | YYYY-MM-DD. With active_to: ads that were running at some point in the window |
| active_to | query | date | - | YYYY-MM-DD, end of the window |
| match | query | enum | any | any | exact (exact phrase) |
| sort | query | enum | relevance | relevance | impressions (most impressions first) |
| limit | query | integer | 30 | Ads per page, 1-50 |
| cursor | query | string | - | 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
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.
Related APIs
- Facebook Ad Details APIOne ad with its creatives, payers and EU (DSA) reach by country, age and gender.
- Facebook Page Ads APIThe profile of an advertiser page and every ad it runs, page by page.
- Facebook Advertiser Search APIFind the advertisers that ran ads on a keyword, with their page ID and category.
- Free Ad Library searchTry the data in the browser: a few free searches a day, no account.
Every parameter and error code is in the ads search reference.
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.