🚀 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)
• 🎬 Optional length filter to skip drama series and long VSLs
• 🎛️ 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",
    "filter_vids_longer_than_sec": 300
  }'

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.

filter_vids_longer_than_sec (optional) 🎬

Cut the drama series out of your results.

Broad keyword searches have a habit of filling up with full-length TV episodes and hour-long VSLs uploaded as ads. They burn through your result limit and bury the creatives you actually came for.

• What this does: Sets a maximum video length. Ads longer than your cutoff are dropped before they reach the dataset.
• Why use it: Filtered ads don't count against max_results_per_url or total_max_results, so the Actor keeps paginating and you still get the full number of ads you asked for — just without the noise.
• Default: 0 (keeps everything)
• Suggested: 300 (5 minutes) — comfortably above any normal direct-response creative.
• Note: This doesn't slow the run down and outputs the same number of results. Ads without a video, or whose length can't be determined, are always kept.

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