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:

```json
{
  "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.