🚀 Facebook Ads Library Scraper

Find, collect, and analyze ads from Facebook Ads Library — fast, repeatably, and at scale. 📈✨

Perfect for:

• 🕵️ Competitor research (what they run, when, and how)
• 🔎 Keyword / brand monitoring across markets
• 📊 Building datasets for BI dashboards, reporting, and analytics
• ⏱️ Automated tracking on a schedule (daily/weekly monitoring)

Just paste one or more Facebook Ads Library search URLs, hit Start ▶️, and get a clean dataset of ads you can export to JSON/CSV/Excel. ✅

What You’ll Get ✅

• 📦 One dataset item per ad (ready for analysis)
• 🔄 Automatic pagination + infinite scrolling
• 🧹 Deduplicated results (no repeats)
• 🎛️ Limits you control (per URL + total)

How To Use 🧭

Run in Apify Console 🖥️

1. Open the Actor in Apify Console
2. Paste your Ads Library URL(s) into the input
3. Click Start ▶️
4. Download results from the Dataset tab (JSON/CSV/Excel) 📥

Run via Apify API 🔌

You can run the Actor from any backend and then fetch dataset items.

1. Start a run:

curl -X POST "https://api.apify.com/v2/acts/<YOUR_USERNAME>~<YOUR_ACTOR_NAME>/runs?token=<APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "start_urls": [
      {"url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&q=shoes&search_type=keyword_unordered"}
    ],
    "max_results_per_url": 100,
    "total_max_results": 500,
    "proxy_country": "us"
  }'

2. When the run finishes, download dataset items from the run’s dataset URL (shown in the run details in Apify Console).

Input ⚙️

start_urls (required) 🌐

List of Facebook Ads Library search URLs.

• Provide URLs exactly as you would open them in the browser (including filters like country, status, media type, and query).
• Each URL is processed independently.

Example:

{
  "start_urls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&q=shoes&search_type=keyword_unordered"
    }
  ]
}

max_results_per_url (optional) 🎯

Maximum number of ads to collect for each URL.

• Default: 100
• Set to 0 for unlimited (not recommended for very broad searches)

total_max_results (optional) 🧮

Maximum total number of ads collected across all URLs.

• Default: 500
• Set to 0 for unlimited

proxy_country (optional) 🌍

See the ads Facebook hides from you.

Facebook often only shows you ads relevant to your location. If you are in the US, you won't see ads running in Germany, even if you search for them.

• What this does: It routes your request through a residential proxy in the country you choose. This tricks Facebook into thinking you are a local user, so you can see all the ads active in that region.
• Why use it: To see exactly what competitors are running in other countries without being blocked or filtered.
• Default: "" (Uses a random high-quality proxy)
• Select a country code: Use the 2-letter ISO code (e.g., us, gb, de, br).
• Note: This is a free feature, but it might be slightly slower because it routes traffic through real device connections.

Output 📤

Results are saved to the default dataset.

Each item represents one ad and includes fields like:

• ad_archive_id
• page_id, page_name
• is_active, start_date, end_date
• publisher_platform
• impressions_text, spend, currency (when available)
• snapshot (creative payload: text, images, videos, cards, links)

Example item:

{
  "ad_archive_id": "886864580481392",
  "page_name": "Example Page",
  "page_id": "123456789",
  "is_active": true,
  "start_date": 1766995200,
  "end_date": 1767772800,
  "publisher_platform": ["FACEBOOK", "INSTAGRAM"],
  "impressions_text": "<100",
  "spend": null,
  "currency": "",
  "snapshot": {
    "caption": "example.com",
    "cta_text": "Learn More",
    "title": "Example Ad",
    "cards": [],
    "images": [],
    "videos": []
  }
}

Pro Tips 💡

• 🎯 Narrow your search (country, status, query) to reduce runtime and cost.
• 🗓️ For monitoring, run the Actor on a schedule and append results to a dataset.
• 🧪 Start small (low limits) to validate your search URL, then scale up.

Notes & Responsible Use 🛡️

• 📌 Data availability depends on what Facebook Ads Library returns for the given search URL.
• 🐢 Some searches may be slower or yield fewer results depending on Facebook-side constraints.
• ⚖️ Make sure your usage complies with Facebook’s terms and applicable laws.

License

Apache-2.0