Meta Ad Library Scraper

Scrape the Facebook / Meta Ad Library at scale. Search by keyword, country, advertiser Page, single ad, or a pasted Ad Library URL, and get clean, structured ad records — brand, dates, ad copy, call‑to‑actions, images/videos, and publishing platforms.

Optionally, turn on ad details to also pull each ad's EU/UK/Brazil reach and age / gender / country demographic breakdowns — transparency data most ad scrapers don't extract.

No Facebook login or third‑party API required.

What you can do with it

• Competitive ad research — see what brands are running, their creative, copy, and CTAs.
• Audience insight — for EU/UK/BR ads (and political ads), get who an ad reached, by age, gender, and country.
• Creative inspiration & monitoring — track active vs. inactive ads, formats (image / video / carousel), and landing pages.
• Advertiser deep‑dives — pull every ad from a specific Facebook Page.

Features

• 🔎 Search by keyword, country, advertiser Page ID, a specific ad ID, or a hand‑built Ad Library URL.
• 🧱 Rich structured output — brand, dates, body text, headline / caption / CTA / link, media URLs, platforms, display format.
• 📊 EU/UK/BR reach + demographics (opt‑in details mode) — unique transparency data.
• 🎯 Filters — ad category, media type, active status, sort order.
• 🧹 Clean JSON, one item per ad, ready for export to CSV/Excel/JSON/API.

Input

Provide one of searchTerm, startUrl, pageId, or adId. A run performs a single Ad Library query.

Field	Description
searchTerm	A single keyword to search for (Meta allows one keyword per query).
country	Country to search, or ALL for global. Default US.
startUrl	An Ad Library URL to scrape verbatim (build one in your browser for full filter control).
pageId	Scrape every ad from a specific advertiser by their Facebook Page ID.
adId	Scrape a single ad by its Ad Library ID.
adType	all, political & issue, housing, employment, credit, or financial ads.
mediaType	all, image, video, meme, or none.
activeStatus	active, inactive, or both.
sortBy	most_relevant (by impressions) or most_recent.
maxResults	Max ads to collect in the run.
scrapeAdDetails	Off by default. When on, also extracts EU/UK/BR reach + demographics (see below).

The scraper runs on residential proxy automatically — no proxy setup needed.

Example input

{
  "searchTerm": "running shoes",
  "country": "US",
  "mediaType": "all",
  "activeStatus": "active",
  "maxResults": 50
}

Output

Each scraped ad is one item in the dataset. Example (basic mode):

{
  "ad_archive_id": "933016365009192",
  "brand_name": "Nike",
  "brand_id": "15087023444",
  "is_active": true,
  "start_date": "2026-05-01T00:00:00+00:00",
  "end_date": "2026-05-30T00:00:00+00:00",
  "publisher_platforms": ["FACEBOOK", "INSTAGRAM"],
  "display_format": "VIDEO",
  "ad_body_text": "Move with the all-new Pegasus.",
  "title": "Nike Pegasus 41",
  "caption": "nike.com",
  "cta_text": "Shop now",
  "cta_type": "SHOP_NOW",
  "link_url": "https://www.nike.com/pegasus",
  "cta_url": "https://www.nike.com/pegasus",
  "thumbnail_url": "https://.../preview.jpg",
  "media": { "type": "video", "video_url": "https://.../ad.mp4", "video_preview_image_url": "https://.../preview.jpg" },
  "brand_categories": ["Sportswear"],
  "brand_like_count": 38000000,
  "brand_profile_picture_url": "https://.../nike.jpg",
  "reach": null,
  "demographic_breakdown": []
}

Always included: ad_archive_id, brand_name, brand_id, is_active, start_date, end_date, publisher_platforms, display_format, ad_body_text, title, caption, cta_text, cta_type, link_url, cta_url, link_description, thumbnail_url, media, and brand metadata (brand_categories, brand_like_count, brand_profile_picture_url, brand_profile_uri).

Added in details mode: reach (EU/UK/BR ad‑delivery reach), demographic_breakdown (per‑country age/gender), location_audience, gender_audience, age_audience.

Two modes

Basic (default) — fast. Brand, dates, copy, CTAs, media, platforms. Works for any country.

Ad details (scrapeAdDetails: true) — clicks into each ad for reach + demographics. This is slower (one click per ad) and capped at 400 ads per run.

ℹ️ Meta only publishes per‑ad reach and demographics for ads delivered in the EU/EEA, the UK, and Brazil, or for political & issue ads anywhere. Details runs for any other country are rejected with a clear message — so you never pay for a slow run that returns no demographic data. Use an eligible country (e.g. DE, GB, BR) or set adType to political & issue ads.

How to use

1. Set your search term (or Page ID / ad ID / URL) and country.
2. Choose filters and Max results.
3. (Optional) Enable Scrape ad details for reach + demographics (eligible regions only).
4. Start the run, then export the dataset as JSON, CSV, or Excel — or pull it via the Apify API.

Pricing

Pay‑per‑result:

Mode	Price
Basic ad	$5 per 1,000 ads
Ad with details (reach + demographics)	$20 per 1,000 ads

Plus standard Apify platform usage (compute + proxy). Details mode is capped at 400 ads per run.

Notes

• Scrapes only public Ad Library data — no login, no private data.
• Runs on residential proxy automatically — no proxy configuration required.
• A run that legitimately finds no matching ads finishes successfully with an empty dataset and a "No ads found" status; genuine errors fail the run with a clear reason.

---

Developer / local setup, project layout, and library usage live in ./DEVELOPMENT.md.