How to Use the Meta Ad Library API in 2026 (And Why It Blocks US Commercial Ads)

By DataHusky Ad Intelligence Engineering Team · Last updated: 2026-11-06 · 8 min read

30-Second Bottom Line: You can query the official Meta Ad Library API (`GET /v21.0/ads_archive`) only after completing government ID verification, and it will ONLY return commercial ads delivered inside the European Union (`ad_reached_countries=['DE','FR',...]`) or global political/social issue ads. If you query `ad_type=ALL` for a US, UK, Canadian, or Australian e-commerce competitor, Meta's Graph API rejects the request with `OAuthException Code 100`.

  • The EU/Political Catch-22: Meta opened commercial API access strictly to comply with EU Digital Services Act (DSA) Article 39—leaving US and global D2C ads locked out of the official API.
  • No Direct Media Files: The official API returns an expiring `ad_snapshot_url` wrapper rather than downloadable 60 Hz / 30 fps 1080p `.mp4` video streams.
  • Zero-Code Workaround: DataHusky Ads monitors any public Page ID across all countries (`US`, `CA`, `GB`, `AU`, `EU`) via headless GraphQL interception—no ID verification or Python code required.

Critical Mistake to Avoid: Do not spend 10 days waiting for Meta physical mail ID verification if your goal is tracking US/UK e-commerce or SaaS competitors—the official API endpoint legally omits non-EU commercial ads.

1. Test Your Target Competitor Query Live API Diagnostic
2. Official Graph API vs. DataHusky Result BLOCKED BY META API
HTTP 400 Bad Request (Graph API /ads_archive)
{ "error": { "code": 100, "message": "Param ad_type=ALL is only supported when ad_reached_countries contains EU member states." } }
DataHusky Headless Pipeline: Extracts 100% of active ads, copy, CTA URLs, and raw MP4 videos for US commercial brands with zero API keys.

What Regulatory & Protocol Standards Show

Under Regulation (EU) 2022/2065 (Digital Services Act / DSA) Article 39[1], Very Large Online Platforms (VLOPs) like Meta are legally required to provide a public, searchable API repository of all commercial advertisements served within European Union member states, including age/gender reach demographics. Outside the EU, Meta enforces strict regional filtering on its OAuth 2.0 (RFC 6749)[2] `/ads_archive` Graph API endpoint, restricting non-EU queries exclusively to political, election, and housing/employment/credit categories[3].

1. Why the Official Meta Ad Library API Returns Zero Results for US E-Commerce Ads

The official Meta Ad Library API (`https://graph.facebook.com/v21.0/ads_archive`) returns an error or zero results for US, UK, Canadian, and Australian commercial brands because Meta restricts `ad_type=ALL` queries strictly to advertisements delivered inside European Union member countries.

Every week, growth engineers and performance marketers spend days completing Meta's 3-step developer onboarding—uploading a high-resolution 300 dpi scan of their passport or driver's license, waiting for a physical verification code in the mail, and creating a Meta Developer App—only to run their first Python request for a US Shopify competitor and hit a wall.

The underlying API pathway enforces a hard geographic gate:

2. How to Query `ads_archive` in Python (For EU Commercial or Political Ads)

If your competitor happens to run ads inside the European Union (or runs political/social issue campaigns), you can query the official `/ads_archive` endpoint using a long-lived OAuth 2.0 User Access Token (`RFC 6749`).

Here is the exact request syntax and parameter schema required by Meta's Graph API[3]:

GET https://graph.facebook.com/v21.0/ads_archive
  ?access_token=EAA...
  &ad_type=ALL
  &ad_reached_countries=['DE','FR']
  &search_page_ids=[10492819384]
  &ad_active_status=ACTIVE
  &fields=id,ad_creation_time,ad_delivery_start_time,ad_creative_bodies,ad_creative_link_titles,ad_snapshot_url,eu_total_reach

However, even when this query succeeds for EU ads, engineering teams immediately discover three technical bottlenecks:

  1. No Direct Video or Image File URLs: The `ad_snapshot_url` field does not return an `.mp4` or `.jpg` file. It returns an interactive web viewer URL that requires a full browser engine running at 60 Hz rendering cadence to execute JavaScript and resolve the temporary `fbcdn.net` media stream.
  2. 60-Day Token Expiration Kinetic Decay: Unlike standard System User tokens, Ads Archive access tokens expire every 60 days if not refreshed via an automated OAuth handshake, breaking unattended cron scripts.
  3. Strict Rate-Limit Throttling (`Binds per Hour`): Meta throttles `/ads_archive` pagination cursor loops aggressively once a script requests more than a few hundred creative records.

3. Architecture Comparison: Official Meta API vs. Third-Party Scrapers vs. DataHusky Ads

Compare the four ways marketing and data teams extract Meta Ad Library creatives across geographic coverage, media archiving, and monthly cost.

Feature / Requirement DataHusky Ads (Managed Pipeline) Official Meta Graph API (`ads_archive`) DIY Playwright / Python Scraper Enterprise Ad-Spy SaaS (Foreplay / MagicBrief)
US, UK, CA & AU Commercial Ads ✓ 100% Supported (`ad_type=ALL`) ✗ Blocked (Political/EU Only) ✓ Supported via Public Web UI ✓ Supported
Government ID Verification ✓ None Required (Instant Setup) ✗ Mandatory Passport + Postal Mail ✓ None Required ✓ None Required
Permanent 1080p MP4 Video Archiving ✓ Auto-Saved to Cloud Vault ✗ Returns Expiring HTML Wrapper ⚠ Requires Custom S3 + FFmpeg Pipe ✓ Saved in Swipe Board
Automated New-Ad Launch Alerts ✓ Instant Email / Slack Diff Alerts ✗ None (Manual Polling Required) ⚠ Breaks When Meta Rotates DOM/GraphQL ⚠ Manual Chrome Extension Saving
Pricing / Unit Economics $19–$29/mo Flat Free (High Engineering Labor Cost) ~$80–$250/mo Residential Proxies + Server $49–$149/mo Per Seat

4. How to Automate Competitor Meta Ad Library Tracking Without Writing Code

Instead of maintaining OAuth tokens or fighting Meta's GraphQL rate limits, you can configure automated 24/7 competitor monitoring in under two minutes:

  1. Grab the Competitor's Public Page URL or Page ID: Open the public Meta Ad Library (`facebook.com/ads/library`), search for your competitor's brand name, and copy either their brand name or the `view_all_page_id=...` number from the URL bar.
  2. Configure Your Alert Cadence & Region: Enter the competitor names in the DataHusky monitor below. Our headless cluster polls the public Ad Library across US, UK, EU, and global regions without triggering the Graph API's non-EU commercial block.
  3. Receive Deduplicated Creative Diffs + Permanent Media: Whenever a competitor launches a net-new video hook, carousel, or landing page offer, DataHusky strips out duplicate dynamic-creative permutations, archives the raw `.mp4` before the `oe=` CDN hex timestamp expires, and dispatches an alert to your inbox.

5. Account Safety: Why You Should Never Scrape Meta Ad Library From Your Personal Facebook Cookie

Running browser-automation extensions or Python Selenium scripts while logged into your personal Facebook account risks immediate Business Manager advertising restrictions.

⚠️ Ad Account & Session Safety Warning:

Never install unverified Chrome extensions that piggyback on your active `c_user` and `xs` Facebook session cookies to bulk-scrape competitor ads. If Meta's anti-automation telemetry flags high-frequency GraphQL calls tied to your personal session, it can restrict your linked Meta Ads Manager profile. Always isolate competitor monitoring in external, cookieless cloud browser workers like DataHusky Ads (which operate in temperature-controlled data centers below 25°C without touching your personal IP or login).

6. 3 Myths About the Meta Ad Library API Debunked

Avoid wasting engineering sprints on outdated tutorials by separating Meta's Marketing API from its Ad Library Archive API.

Myth #1: "The Meta Marketing API lets you pull competitor ad spend and ROAS."

The Reality: Meta's Marketing API (`/act_/insights`) only returns ROAS, CPC, and spend for ad accounts where you hold Admin/Advertiser permissions. For competitors, the public Ad Library only exposes EU reach counts (`eu_total_reach`), political spend brackets, and active longevity dates (`ad_delivery_start_time`).

Myth #2: "Once approved for the Meta Ad Library API, you can query `ad_type=ALL` worldwide."

The Reality: Even with full ID verification and a live Developer App, passing `ad_type=ALL` with `ad_reached_countries=['US']` returns an immediate HTTP 400 error. Non-political ads are only exposed via the official API when delivered in the EU/EEA.

Myth #3: "Saving the `ad_snapshot_url` from the API preserves the ad forever."

The Reality: As soon as a commercial advertiser pauses or deletes a non-EU campaign, it vanishes from the public Ad Library—and any unarchived media URLs return `URL signature expired`.

7. Frequently Asked Questions

Does the Meta Ad Library have a public API for all ads?

No. While Meta provides the Graph API /ads_archive endpoint, it only returns commercial ads delivered in the European Union (under EU Digital Services Act Article 39) or ads classified under Social Issues, Elections, or Politics worldwide. Querying ad_type=ALL for US, Canadian, or Australian e-commerce ads returns an API permission error or empty array.

Why do I need government ID verification to access the Meta Ad Library API?

Because the /ads_archive endpoint was originally built for election transparency, Meta requires every developer to complete personal identity verification (government passport/driver's license + physical mailing confirmation) before granting Ads Archive API access.

Does the Meta Ad Library API give direct MP4 video download links?

No. The official API returns an ad_snapshot_url that requires an authenticated browser session to render, rather than raw 1080p MP4 video files or permanent image assets.

How can I monitor US and global competitor Facebook ads automatically without using the restricted API?

DataHusky Ads uses a managed headless browser cluster that queries the public Meta Ad Library frontend across any country (US, UK, CA, AU, EU), extracts native MP4/WebP creatives, and sends instant email/Slack alerts when a competitor launches a new campaign.


8. Technical Standards & References

  1. European Parliament and Council (2022). Regulation (EU) 2022/2065 on a Single Market For Digital Services (Digital Services Act), Article 39: Additional online advertising transparency for Very Large Online Platforms. Official Journal of the European Union.
  2. Hardt, D. (2012). RFC 6749: The OAuth 2.0 Authorization Framework (Access Token Lifecycle & Bearer Authentication). Internet Engineering Task Force (IETF).
  3. Meta Platforms, Inc. (2026). Meta Graph API Reference: /ads_archive Endpoint Parameters & Country Restrictions. Meta for Developers Documentation.

Explore Related Ad Intelligence Guides:

About the Author: DataHusky Ad Intelligence Engineering Team

The DataHusky Ad Intelligence Engineering Team builds autonomous headless browser clusters, creative deduplication pipelines, and permanent S3 media vaults for performance marketing agencies and D2C growth teams.

Last updated: 2026-11-06