Facebook Ad Library API — Ads Archive Search

Search the official Facebook Ads Archive (Ad Library) and get clean JSON: ad creatives, spend ranges, impression ranges, targeting, demographics and publisher platforms.

No scraping, no browser, no blocks — this uses Meta's official ads_archive Graph API endpoint.

Why this Actor

Competing Facebook ad scrapers charge per ad and break whenever Facebook changes its HTML. This Actor uses the official API, so it stays stable and returns structured fields that scrapers often miss — including spend and impressions ranges and demographic distribution.

Endpoints

Method	Path	Token required
GET	/search?q=...	yes
GET	/health	no

# Search active ads mentioning "coffee" worldwide
curl "https://<container-url>/search?q=coffee&country=ALL&limit=50"

# Limit to one country + video ads only
curl "https://<container-url>/search?q=coffee&country=ID&media_type=VIDEO"

Parameters: q, country (ISO-2 or ALL), limit (≤250), ad_type (ALL | POLITICAL_AND_ISSUE_ADS), media_type (ALL | IMAGE | VIDEO | MEME | NONE).

Output

{
  "query": "coffee",
  "country": "ALL",
  "count": 20,
  "hasMore": true,
  "items": [
    {
      "id": "123…",
      "pageName": "Example Coffee Co",
      "body": ["Fresh beans, delivered."],
      "linkTitle": ["Order now"],
      "deliveryStart": "2026-09-01",
      "deliveryStop": "2026-10-01",
      "spendRange": {"lower_bound": "100", "upper_bound": "199"},
      "impressionsRange": {"lower_bound": "10000", "upper_bound": "19999"},
      "publisherPlatforms": ["facebook", "instagram"],
      "snapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=…"
    }
  ]
}

Getting a token (free)

1. Go to https://developers.facebook.com/tools/explorer
2. Select Get User Access Token and grant the ads_archive permission
3. Paste it into the Actor input fbAccessToken (or FB_ACCESS_TOKEN env var)

Note: ads_archive access requires identity/address verification for some accounts — follow the prompts in the Graph API Explorer.

Local development

pip install -r requirements.txt
uvicorn src.main:app --reload

Related searches

facebook ad library api, ad library scraper, competitor ads, ad spy api, meta ads data, ad intelligence, ad creative search