The Meta Ad Library is the most comprehensive public ad archive in advertising. The browser interface is fine for spot-checks but breaks the moment you need recurring competitor scans, structured data, or programmatic alerts. This guide walks every path to access the library at scale: the official Meta Ad Library API, scraper patterns, the legal lines, and the AI-agent shortcut that skips most of the build.
What's in the Meta Ad Library
Note
Definition. The Meta Ad Library is a public archive maintained by Meta containing every ad currently running on Facebook, Instagram, Messenger, Audience Network, and Threads. It exists because of EU and US political ad transparency regulations that have been expanded to cover all advertising. Anyone can browse it at facebook.com/ads/library; developers can query it programmatically through the Meta Ad Library API.
For a non-technical walkthrough of the browser interface, see How to Use the Meta Ad Library. The rest of this guide assumes you want to query the library at scale. For competitor research automation, internal analytics, custom dashboards, or AI agent workflows.
The library exposes:
| Field | Available |
|---|---|
| Ad creative (image, video, copy) | Yes for all ads |
| Advertiser (Page) name and ID | Yes |
| Countries the ad ran in | Yes |
| Platforms (FB, IG, Messenger, AN, Threads) | Yes |
| Ad active status | Yes |
| Languages | Yes |
| Impressions and spend ranges | Political and issue ads only |
| Demographic delivery breakdown | Political and issue ads only |
| Targeting (audience, interests, behaviors) | Never |
| Performance (CTR, CVR, ROAS) | Never |
Commercial ads expose creative and metadata; political and issue ads expose impressions, spend, and demographic delivery on top.
The official Meta Ad Library API
Meta provides a public API that returns the same data as the browser interface in JSON. It's the default path for any production integration.
Access requirements
The API is gated. Three things are required:
- A registered Meta for Developers app
- Identity verification of the developer (passport or driver's license)
- Acceptance of Meta's Ad Library API terms
Approval typically takes 1-2 weeks. Some categories (political research) get priority routing.
Authentication
Standard Meta Graph API token flow. The API accepts:
- App access tokens (server-side use; do not expose to browsers)
- User access tokens (limited; not the production path)
- System user access tokens (recommended for scheduled jobs)
System user tokens with ads_archive scope are the right choice for recurring scrapers. They don't expire and can be rotated independently of any one developer's account.
Endpoint shape
The primary endpoint is https://graph.facebook.com/v19.0/ads_archive. Required parameters:
| Parameter | Required | Notes |
|---|---|---|
access_token | Yes | System user token recommended |
ad_reached_countries | Yes | Array of ISO country codes, e.g. ["US"] |
search_terms | One of | Keyword search across ad copy |
search_page_ids | One of | Specific advertiser Page IDs (more precise) |
ad_active_status | No | ACTIVE, INACTIVE, or ALL |
ad_type | No | ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, etc. |
fields | No | Comma-separated list of fields to return |
limit | No | Max 1000 per call (default 25) |
Example request shape:
curl -G "https://graph.facebook.com/v19.0/ads_archive" \
--data-urlencode "access_token=${META_TOKEN}" \
--data-urlencode "ad_reached_countries=[\"US\"]" \
--data-urlencode "search_terms=AI marketing agent" \
--data-urlencode "ad_active_status=ACTIVE" \
--data-urlencode "fields=id,page_name,ad_creative_bodies,ad_creative_link_titles,ad_delivery_start_time,publisher_platforms" \
--data-urlencode "limit=100"
The response is paginated via paging.cursors.after. Most production integrations loop until the next URL is empty.
Rate limits and quotas
Meta caps the Ad Library API at roughly 200 calls per hour per app for standard access, with quota reset on a rolling window. Higher quota is granted case-by-case for academic research and approved commercial partners.
Practical implications:
- A 50-brand competitor scan with 100 ads each is 5,000 ad records, which is at minimum 50 paginated calls. At 200/hr you can run two of these scans per hour.
- Daily polling at scale needs queue management; a naive script will hit the limit and get throttled.
- If you need higher throughput, the right path is either an approved partner application or pre-built tools (see below) that aggregate quota across customers.
Data freshness
The API reflects the current state of the library. Ads are visible within minutes of going live. Inactive (paused or rejected) ads disappear from the API at the same time they disappear from the browser interface. There is no historical archive maintained by Meta for commercial ads. If you want history, you must snapshot it yourself.
Custom scraping the library
Building a scraper against facebook.com/ads/library directly (without the API) is technically possible but operationally fragile.
The shortlist of issues:
| Issue | Detail |
|---|---|
| Terms of service | Meta's TOS prohibits unauthorized scraping. Sustained scraping risks legal action and IP bans for the operating organization. |
| Page structure changes | The library's HTML and underlying GraphQL queries change every few weeks. A scraper that worked Monday can break Friday. |
| IP rate limiting | Meta blocks IPs that hit the public site at scale within hours. Rotating residential proxies extend the lifespan but raise cost and legal complexity. |
| Cloudflare-style challenges | The library puts CAPTCHAs in front of suspicious traffic. Headless browser automation (Playwright, Puppeteer) helps but isn't a permanent fix. |
| Data quality | Scraped data lacks the structured fields the API exposes; you have to parse rendered HTML or intercept network requests. |
For most teams, the API is the right answer. Custom scraping makes sense in three narrow cases:
- Research firms with legal review and significant infrastructure
- Operators in jurisdictions where Meta's API access is restricted
- Scenarios that need data the API does not expose (e.g. impression count estimates from rendered metadata)
If you must scrape, use Playwright or similar with rotating residential proxies, throttle aggressively (1 request per 5+ seconds per IP), parse the page's GraphQL responses rather than the rendered HTML, and accept that the scraper will break monthly.
Third-party APIs and tools
Several vendors aggregate Meta Ad Library access (and other ad library access) and expose it through their own API. The trade-off is paying a subscription in exchange for managed scraping, broader historical data, and unified access across multiple ad libraries.
| Tool | Coverage | API access | Best for |
|---|---|---|---|
| Hyper | Meta, Google Ads Transparency Center, TikTok Creative Center, LinkedIn Ad Library | Yes (MCP and REST) | Brands and agencies wanting library data inside their own AI marketing agent |
| GoMarble Spy | Meta, TikTok | Yes via API | DTC brands doing structured competitor reports |
| Foreplay | Meta, TikTok | Limited API | Creative teams building swipe files |
| Magic Brief | Meta, TikTok | Yes via API | Creative ops teams tagging ads at scale |
| AdSpy | Meta, TikTok, YouTube, Pinterest | Yes via API | Affiliate marketers and high-volume DTC |
Vendor APIs typically include:
- A unified schema across multiple ad libraries
- Historical archives Meta does not maintain (vendors snapshot regularly)
- Higher quotas than direct Meta API access
- Search and filter capabilities the official API does not expose
- Alerts and webhooks for new competitor ads
The cost is a recurring subscription (typical range 99-499 USD/month for SMB tiers; enterprise tiers vary). The value is skipping the access approval, rate limit management, and continuous schema maintenance.
Hyper MCP: skip the build
The shortest path for any team that wants Meta Ad Library access plus broader ad intelligence inside an AI workflow:
Hyper is an AI marketing agent that includes built-in scraping for Meta Ad Library, Google Ads Transparency Center, TikTok Creative Center, and LinkedIn Ad Library. The agent runs on a recurring schedule, snapshots competitor sets, and feeds findings into the agent's own creative briefs.
For developers, the meaningful detail is that Hyper exposes all this work through the Hyper MCP, a Model Context Protocol server. Any MCP-compatible AI client (Claude, Cursor, ChatGPT desktop, OpenClaw) can call Hyper's competitor research tools as if they were native AI capabilities. The integration is configuration, not code.
Concrete uses:
- Inside Claude: "Pull the last 30 days of competitor ads for [brand list] and surface what's new this week". runs through Hyper, returns a structured summary.
- Inside Cursor: Build dashboards that pull from Hyper's competitor data without writing scraping infrastructure.
- Inside ChatGPT: Run weekly competitor reports as a saved prompt; the data comes from Hyper's recurring scrapes, not from the chat session itself.
For teams already running paid ads on Meta, Google, TikTok, or LinkedIn, the same Hyper agent that handles campaigns also handles the competitor intelligence. Same login, same dashboard, same MCP. You skip the API approval, the scraper maintenance, and the data pipeline build.
Autonomous marketing
Grow your business faster with AI agents
- Automates Google, Meta + 5 more platforms
- Handles your SEO end to end
- Improves website conversions
- Runs social media for you
Frequently asked questions
Q: Is the Meta Ad Library API free?
Yes. The Meta Ad Library API is free to use, but access requires identity verification through Meta for Developers and acceptance of Meta's Ad Library API terms. Approval typically takes 1-2 weeks.
Q: What's the rate limit on the Meta Ad Library API?
Standard access is approximately 200 calls per hour per app, with quota reset on a rolling window. Higher quotas are granted case-by-case for academic research and approved commercial partners. For most use cases, queue management and pagination cursors are essential.
Q: Can I scrape the Meta Ad Library directly?
Technically yes; in practice it's fragile and against Meta's terms of service. Page structure changes weekly, IP rate limits trigger within hours, and CAPTCHAs gate suspicious traffic. The API is the right path for almost all production integrations. Scraping makes sense only for research firms with legal review and significant infrastructure.
Q: Does the Meta Ad Library API show advertiser spend?
Only for political and issue ads. Commercial ads do not expose spend through the API or the browser interface. If you need spend signals for commercial advertisers, third-party tools like SimilarWeb estimate them from indirect signals (traffic, share of voice), but these are estimates, not actuals.
Q: What is the difference between the Meta Ad Library API and a third-party tool like Hyper or AdSpy?
The official API gives you raw access to current Meta ads. Third-party tools layer aggregation on top: unified schema across multiple ad libraries (Google, TikTok, LinkedIn), historical archives Meta does not maintain, higher quotas, and built-in search and alerting. The trade-off is a subscription cost in exchange for skipping the API approval and integration build.
Q: Can I get historical Meta ads through the API?
No. Meta does not maintain a historical archive for commercial ads. Once an ad goes inactive, it disappears from the API. If you want history, you must snapshot the API yourself on a recurring schedule, or use a third-party tool that maintains its own archive.
Q: What's the best way to query the Meta Ad Library from an AI agent?
Use the Hyper MCP. It exposes Meta Ad Library scraping (plus Google Ads Transparency Center, TikTok Creative Center, and LinkedIn Ad Library) as MCP tools that any AI client (Claude, Cursor, ChatGPT, OpenClaw) can call. The integration is configuration only. No code, no API approval, no rate limit management.
Q: What does the Meta Ad Library API return?
Standard fields include ad ID, page name, ad creative body, ad creative link titles, ad delivery start time, publisher platforms, and ad reached countries. Political and issue ads add impressions, spend, and demographic delivery breakdowns. Targeting (audience, interests, behaviors) and performance metrics (CTR, CVR, ROAS) are never returned for any ad type.
What to do next
For developers building a one-off Meta Ad Library integration:
- Apply for Meta Ad Library API access through Meta for Developers.
- Generate a system user access token with
ads_archivescope. - Build pagination logic against the
ads_archiveendpoint. - Plan for rate limit management and schema versioning.
For teams that want competitor intelligence inside an AI workflow without the API integration:
Hyper handles Meta Ad Library, Google Ads Transparency Center, TikTok Creative Center, and LinkedIn Ad Library scraping. Exposed through the Hyper MCP for use inside any MCP-compatible AI client. Free 30-day trial, paid plans from 49 USD/month.