levalencia 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
- Takes a company name, keyword, or Facebook Page URL
- Constructs a Meta Ad Library URL with the search query and filters
- Calls the Apify
apify/facebook-ads-scraperactor via REST API - Polls until the run completes, then fetches the dataset
- 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-urlfor 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 allto 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.