Meta Ad Library API
Search Facebook and Instagram ads by keyword, pull everything one Page is running, or open a single ad by its archive id — each a single POST returning structured JSON. No Meta identity verification and no developer app.
50 free credits on signup. No card, no ID verification.
{ "data": { "ads": [ { "ad_archive_id": "1785179045778580", "collation_count": 1, "is_active": false, "page_id": "721404351056614", "page_name": "IControl: Easy Widgets Themes", "page_profile_url": "https://business.facebook.com/61578892468353", "page_categories": [ "Topic" ], "page_like_count": 4358 } ], "count": 30, "total_results": 1000, "total_is_capped": true, "has_next_page": true }, "response_time": 2180, "credits_used": 1, "credits_remaining": 4686}Live call against the real endpoint — 3 free runs, then it's your own key.
What is the Scavio Meta Ad Library API?
The Scavio Meta Ad Library API is a REST API that returns Facebook and Instagram ad library data as structured JSON. You send a keyword, a numeric Page id or an ad archive id to one of 3 POST endpoints with your API key, and get back matching ads with their advertiser Page, copy, creative and active status.
- 3
- endpoints, all live in production
- 1
- credit per call, every endpoint
- 0
- identity verifications required
Three endpoints, three ways in
By keyword, by advertiser, or straight to one ad.
Keyword search
POST /api/v1/meta-ads/searchSearch the Facebook and Instagram ad library by keyword and get every matching ad with its advertiser Page, copy and active status.
Advertiser's ads
POST /api/v1/meta-ads/advertiserEverything one Page is running, by numeric Page id — the cleanest way to see a competitor's full paid social footprint.
Ad detail
POST /api/v1/meta-ads/adOne ad in full by its archive id, including the advertiser Page and creative, for when you need the record rather than the list.
All 3 Meta Ad Library endpoints
Every route is a POST, returns JSON, and takes the same API key. Note the hyphen: the segment is meta-ads.
| Endpoint | Returns | Credits |
|---|---|---|
Keyword search/api/v1/meta-ads/search | Ads across Facebook and Instagram — advertiser, copy, status | 1 |
Advertiser's ads/api/v1/meta-ads/advertiser | Every ad one Page is running, by numeric Page id | 1 |
Ad detail/api/v1/meta-ads/ad | One ad in full by archive id — Page, copy and creative | 1 |
50 free credits on signup covers 50 calls of any kind. See plans
A keyword to a competitor's whole library
Search by keyword, then pull everything that Page runs. The response on the right is a real capture, field names and all.
from scavio import ScavioClient
client = ScavioClient(api_key="sk_live_your_key")
# note the hyphen in the path: /api/v1/meta-ads/...
res = client.meta_ads.search(query="nike", country="US")
for a in res["data"]["ads"]:
print(a["ad_archive_id"], a["page_name"], a["is_active"])
# Everything one Page runs - 1 credit
page_ads = client.meta_ads.advertiser(page_id="721404351056614"){
"data": {
"ads": [
{
"ad_archive_id": "1785179045778580",
"collation_count": 1,
"is_active": false,
"page_id": "721404351056614",
"page_name": "IControl: Easy Widgets Themes",
"page_profile_url": "https://business.facebook.com/61578892468353",
"page_categories": ["Topic"],
"page_like_count": 4358
}
],
"count": 30,
"total_results": 1000,
"total_is_capped": true,
"has_next_page": true
},
"response_time": 2180,
"credits_used": 1,
"credits_remaining": 4686
}Why not Meta's official Ad Library API?
It exists and it is free, but for commercial ads it is far narrower than most people expect.
Meta Ad Library API
- Requires identity verification and a Meta developer app before any access
- Full search is scoped to social issue, election and political ads
- Commercial ad coverage is limited and varies by country
- Access can lapse when verification expires
Scavio Meta Ad Library API
- One API key, issued at signup — no verification, no developer app
- Commercial ads by keyword, by Page or by archive id
- is_active on every ad, so live and historical are separable
- Same key and JSON envelope as 30 other Scavio platforms
Scavio returns data Meta itself publishes for transparency, and never authenticates as a Meta user.
What developers build with it
Competitor paid-social monitoring
Pull everything a competitor Page is running and diff it weekly. New campaigns, message changes and quiet pauses all surface without anyone scrolling a feed.
advertiserCreative research and swipe files
Search a category by keyword to collect the ad copy and creatives actually in market, with each ad's active status so you can weight what is still running.
search + adBrand protection
Find ads using your brand name or assets from Pages you do not control, with the advertiser Page and its like count attached for triage.
searchMarket entry and category sizing
See who is advertising in a category and how heavily before committing budget. Page categories and like counts give quick context on each advertiser.
search + advertiserAgent tools for ad research
Point an agent at the MCP server and the ad library becomes a callable tool — what is this brand running, who else advertises here — with one key.
MCP + RESTHow to get Meta ad data as JSON
- 1
Get an API key
Sign up for a Scavio account and copy your key from the dashboard. You get 50 credits free on signup, with no card required and no Meta identity verification.
- 2
Mind the hyphen in the path
The route is /api/v1/meta-ads/search, with a hyphen — not metaads. Send {"query": "nike", "country": "US"} there with an Authorization: Bearer header.
- 3
Treat totals as a floor
The response carries total_is_capped. When it is true, total_results is a ceiling Meta applies rather than the true count, so page with has_next_page instead of trusting the number.
Meta Ad Library API FAQ
What is the Scavio Meta Ad Library API?
+
It is a REST API that returns Facebook and Instagram ad library data as structured JSON. Three POST endpoints cover keyword search across the library, every ad one Page is running by numeric Page id, and a single ad by its archive id. You authenticate with a Scavio API key.
Who are these endpoints for?
+
Paid-social and competitive intelligence teams; agencies building creative swipe files; brand-protection teams; developers building ad-intelligence products; AI agent builders wiring the ad library in as an MCP or SDK tool; and analysts sizing category spend. Same API for all of them.
How is this different from Meta's own Ad Library API?
+
Meta's official API requires identity verification and a developer app, and its full search is scoped to ads about social issues, elections and politics in supported countries. Commercial ads are far more limited there. This reads the public library without verification.
Why is the path meta-ads with a hyphen?
+
Because that is the actual route segment: /api/v1/meta-ads/search. Writing metaads without the hyphen returns a 404, and it is a mistake worth calling out because the platform is often referred to without one.
How much does a request cost?
+
Every Meta Ad Library endpoint costs 1 credit. New accounts get 50 free credits on signup, one time, with no card required. Paid plans start at $30 per month for 7,000 credits.
Why is total_results sometimes capped?
+
Meta caps how many results it will report for a broad query, and the response tells you so with total_is_capped. When that flag is true, treat total_results as a floor and page using has_next_page rather than trusting the figure.
Can I see whether an ad is still running?
+
Yes. Each ad carries is_active, so you can separate live campaigns from historical ones — which matters, because a swipe file full of paused ads is a museum rather than a competitive signal.
What does the response look like?
+
The API wraps the payload under a data key and adds credits_used and credits_remaining. Each ad carries ad_archive_id, collation_count, is_active, page_id, page_name, page_profile_url, page_categories and page_like_count, alongside count, total_results, total_is_capped and has_next_page.
Which languages and tools are supported?
+
Official Python (pip install scavio) and JavaScript/TypeScript (npm i scavio) SDKs, a remote MCP server at mcp.scavio.dev for AI agents, and an n8n community node. Any language can call the REST endpoints directly with an HTTP client.
Is using Ad Library data legal?
+
Scavio returns data Meta itself publishes for transparency purposes, and does not authenticate as a user. You remain responsible for how you use it, including compliance with Meta's terms. Talk to your own counsel for your specific use case.
Explore more of Scavio
Google Ads Transparency API
Advertisers, ads and creative history.
Instagram API
Profiles, posts, reels and hashtag search.
TikTok API
Profiles, videos, comments and hashtags.
Threads API
Profiles, posts, replies and search.
MCP server
Every platform as a callable tool for agents.
Pricing
Credit packs and plans, no per-platform surcharge.
Start pulling Meta ads today
50 free credits on signup, no card. Your first request is a POST with a keyword in it.