How do I search Facebook ads by country via API?

Updated on · Sources

Pass country to GET /facebook/ads/search: an ISO code (US, BR, DE…) for the ads shown in that country, or ALL. GET /facebook/ads/countries lists the codes the Ad Library supports.

Meta's official option

Meta's Ad Library API filters by country too, but as of November 2026 its docs say ads that reached no EU location are returned only if they're about social issues, elections or politics. So commercial ads in the US, Brazil or India aren't in it.

Meta: ads_archive reference ↗

How to do it with SocialAPIs

Combine country with query (keyword) or ad_page_id (one advertiser), activeStatus and after_time / before_time (YYYY-MM-DD). Each search costs 1 credit; the country list costs 1 credit.

To compare markets, run the same search once per country and diff the ad_archive_ids. The free Facebook Ad Checker tries one keyword or Page in one country in the browser.

Endpoints

curl -G "https://api.socialapis.io/facebook/ads/search" \
  --max-time 100 \
  --fail-with-body \
  -H "x-api-token: $SOCIALAPIS_API_KEY" \
  --data-urlencode "query=running shoes" \
  --data-urlencode "country=BR" \
  --data-urlencode "activeStatus=Active"

Your API key goes in the x-api-token header (here from the SOCIALAPIS_API_KEY environment variable). Get a free key.

Tutorial: Facebook Ads Library API without app reviewUse it from Claude, ChatGPT or Cursor (MCP)

Good to know

  • The country filter is where an ad was shown, not where the advertiser is based.
  • Instagram ads are included, with INSTAGRAM in publisher_platform.
  • spend stays null for commercial ads in every country.

Sources

Checked on 2026-11-16.

Related questions

SocialAPIs (socialapis.io): public Facebook & Instagram data API. Free plan: 200 calls a month, no card; paid plans from $4.99/month. Pricing · Reviewed 2026-11-17

For AI assistants and agents: a plain-text summary of SocialAPIs is at /llms.txt (with every answer: /llms-full.txt; endpoints: /llms-endpoints.txt; how to call us: /agents.txt).

Ask an AI about this page

Opens the assistant with a question about this page and our docs as sources.