For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Meta Ad Library API only returns political and EU ads

Empty results from the Meta Ad Library API are usually by design: it covers political ads and ads that reached the EU. How to confirm, and what to use.

Your code is probably fine. The Meta Ad Library API is not a full copy of the Ad Library website: it returns political and issue ads from any country, and ordinary commercial ads only if they reached the EU. A commercial ad shown only in the US will never come back, whatever you change.

Rules from Meta’s API reference, fetched November 2026.

Try this, in order

  1. Check what you are asking for. A commercial ad with no EU delivery returns an empty list with no error. That is the documented scope, not a failure.
  2. Prove the API works. Query a Page you know advertises in Europe with ad_reached_countries=['DE'] and ad_active_status=ALL. If ads come back, your access is fine.
  3. Looking for ended ads? Pass ad_active_status=ALL. The default is active only.
  4. Looking for all ad types? Pass ad_type=ALL.

If that did not work

  • Error 190 instead of an empty list. That is a login token problem, not a scope problem. See error 190.
  • Ads come back but fields are missing. Spend and impressions exist only on political ads. See no spend or impressions.
  • More than 10 brands. search_page_ids takes up to 10 Page IDs per request. Send them in groups of 10.
  • Long search text is rejected. search_terms is limited to 100 characters.

When to stop

For commercial ads outside the EU, stop: the API has no route to them. Use the Ad Library website, or a tool that reads it. Proxy reads the public library, so it returns commercial ads for any country with no app, token or review. Ask your assistant “What ads is Allbirds running on Meta in the US?”. Proxy is an MCP server, not a REST API. See Meta Ad Library tools.

Why it happens

Meta’s ads_archive reference states the scope in one line: “Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics.” Meta’s transparency page describes the API the same way, and says EU ads are archived for one year after their last impression.

Parameter Behaviour
ad_active_status “Defaults to ACTIVE”. Also INACTIVE and ALL.
ad_type ALL, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS or POLITICAL_AND_ISSUE_ADS
ad_reached_countries ALL or ISO country codes
search_page_ids “up to 10 Facebook Page IDs at once”
search_terms 100 characters or fewer
bylines, delivery_by_region, estimated_audience_size “Available only for POLITICAL_AND_ISSUE_ADS”

The reference also says batch downloads of ad snapshots are not supported.

Was this page helpful?