athina-ai/meta-ad-scraper

Meta Ad Library Scraper

Scrape ads from Meta's Ad Library using the Apify apify/facebook-ads-scraper actor. Covers Facebook, Instagram, Messenger, Threads, and WhatsApp.

Quick Start

Requires APIFY_API_TOKEN env var (or --token flag). Install dependency: pip install requests.

# Search ads by company name
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "Nike"

# Search with country filter
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "Shopify" --country US

# Search by keyword (broader than company name)
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "project management software"

# Limit results
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "HubSpot" --max-ads 20

# Search by Facebook Page URL directly
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --page-url "https://www.facebook.com/nike"

# Only active ads (default), or all ads
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "Salesforce" --ad-status all

# Human-readable summary
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "Stripe" --output summary

How It Works

1. Takes a company name, keyword, or Facebook Page URL
2. Constructs a Meta Ad Library URL with the search query and filters
3. Calls the Apify apify/facebook-ads-scraper actor via REST API
4. Polls until the run completes, then fetches the dataset
5. Parses and outputs ad data as JSON or human-readable summary

Resolving Company Name → Ads

The script handles the advertiser lookup automatically:

• Company name: Constructs a search URL like facebook.com/ads/library/?q=CompanyName — the Apify actor searches Meta's Ad Library for matching advertisers
• Page URL: If you have the Facebook Page URL, pass it via --page-url for exact matching
• Domain: You can also pass a domain and the script will search for it

No need to manually find Page IDs. The Apify actor resolves the search internally.

CLI Reference

| Flag | Default | Description | |------|---------|-------------| | --company | required* | Company name or keyword to search | | --page-url | none | Facebook Page URL for exact advertiser match | | --country | ALL | 2-letter country code (US, GB, DE, etc.) or ALL | | --ad-status | active | active or all (includes inactive) | | --max-ads | 50 | Maximum number of ads to return | | --output | json | Output format: json or summary | | --token | env var | Apify token (prefer APIFY_API_TOKEN env var) | | --timeout | 300 | Max seconds to wait for the Apify run |

*Either --company or --page-url is required.

Output Fields

Each ad in the output contains:

{
  "ad_id": "123456789",
  "page_name": "Nike",
  "page_id": "123456789",
  "ad_text": "Just Do It. Shop the latest...",
  "ad_creative_link_title": "Nike.com",
  "ad_creative_link_description": "Free shipping on orders...",
  "ad_creative_link_url": "https://nike.com/...",
  "image_url": "https://...",
  "video_url": "https://...",
  "ad_delivery_start_time": "2026-01-15",
  "ad_delivery_stop_time": null,
  "currency": "USD",
  "spend_lower": 100,
  "spend_upper": 499,
  "impressions_lower": 1000,
  "impressions_upper": 4999,
  "platforms": ["facebook", "instagram"],
  "status": "ACTIVE"
}

Cost

~$5 per 1,000 ads scraped on Apify Free plan. Paid plans are cheaper ($3.40-$5/1K).

Common Workflows

1. Competitor Ad Research

python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "Competitor Name" --country US --max-ads 100 --output summary

2. Industry Ad Landscape

# Search by keyword to see all advertisers in a space
python3 skills/meta-ad-scraper/scripts/search_meta_ads.py \
  --company "CRM software" --max-ads 50

3. Compare Multiple Competitors

Run the script multiple times for each competitor and compare creative approaches, messaging, and spend ranges.

Important Notes

• EU/UK ads are most complete: Meta archives all ads shown in EU/UK. For US-only ads, coverage may be limited to political/issue ads.
• Active vs All: By default only active ads are returned. Use --ad-status all to include historical ads.
• Rate limits: Apify handles rate limiting internally. For large scrapes, increase --timeout.

Configuration

See references/apify-config.md for detailed API configuration, token setup, and rate limits.