Meta Ad Library Scraper

📢 Meta Ad Library Scraper is a powerful Apify Actor designed to discover, track, and collect live advertising creative data directly from the Meta Ad Library using a real headless browser and GraphQL network interception. This tool provides comprehensive Meta Ad Library intelligence including ad copy text, page name, image creative, video creative, and call-to-action link for any keyword or country. Whether you're building a competitor ad monitoring tool, tracking creative trends, or conducting market research, the Meta Ad Library Scraper delivers actionable Meta Ad Library insights efficiently.

With direct GraphQL network interception, recursive JSON parsing, scroll-triggered pagination, and reliable Apify Dataset delivery, the Meta Ad Library Scraper ensures comprehensive Meta Ad Library coverage across any search keyword. It focuses on key Meta Ad Library signals including ad text, creative assets, and advertiser page name, making it an essential tool for competitive advertising research and creative intelligence.

---

📋 Table of Contents

• Features
• Data Source
• How It Works
• Input
• Output
• Technical Stack
• Data Fields
• Use Cases
• Quick Start
• Configuration
• Performance
• Important Notes
• License & Legal

---

🔥 Features

• Real Browser Rendering – Uses Playwright (Chromium) to load the Meta Ad Library search page exactly as a real visitor would see it.
• GraphQL Network Interception – Listens for and captures Meta's internal GraphQL responses as they stream in, rather than scraping rendered HTML.
• Recursive JSON Parsing – Deeply searches every intercepted GraphQL payload for ad snapshot objects, regardless of nesting depth.
• Keyword & Country Targeting – Searches the Meta Ad Library for any keyword within a specific country's active ad set.
• Automation Detection Evasion – Masks the navigator.webdriver flag to reduce the chance of bot detection.
• Scroll-Triggered Pagination – Automatically scrolls the page to trigger additional backend GraphQL requests and capture more ads.
• Multi-Asset Extraction – Pulls ad copy text, image URL, video URL, and CTA link from each captured Meta Ad Library record.
• Deduplication – Removes duplicate ad records by ad ID or ad text before saving.
• Residential Proxy Support – Apify residential proxy for reliable Meta Ad Library access.
• Configurable Item Cap – Stop collecting once a set number of clean Meta Ad Library creatives has been reached.
• Real-Time Dataset Push – Pushes all collected Meta Ad Library records to Apify Dataset in a single batch.
• Graceful Error Handling – Continues the run even if individual network responses fail to parse.

---

📊 Data Source

Meta (Facebook) Ad Library

• Authority: Meta's own public-facing Ad Library (facebook.com/ads/library) and its internal GraphQL API
• Access Method: Headless Chromium via Playwright, with network response interception on GraphQL endpoints
• Coverage: Any active, publicly listed ad in the Meta Ad Library matching the given keyword and country
• Data: Raw GraphQL ad snapshot objects captured directly from the network stream
• Access: Public Ad Library interface, no API key required
• Update Frequency: Reflects each Meta Ad Library ad's current live/active state at time of run

---

⚙️ How It Works

The Meta Ad Library Scraper launches a real headless browser and navigates to the Ad Library search results for a given keyword and country. As the page loads, it attaches a network response listener that watches for Meta's internal GraphQL endpoints and captures any response containing ad snapshot data. The Actor then scrolls the page repeatedly to trigger additional backend GraphQL calls, capturing more ads with each scroll. Every intercepted payload is recursively searched for ad archive objects, from which ad text, page name, image URL, video URL, and CTA link are extracted. Captured ads are deduplicated by ad ID (or a text fingerprint when no ID is present) before being pushed to the Apify Dataset.

Key Processing Steps:

1. Input Parsing – Accept a search keyword, country code, max item count, and proxy setting
2. Proxy Setup – Configure Apify residential proxy for the browser session
3. Browser Launch – Start a headless Chromium instance with automation-detection evasion
4. Network Listener Setup – Attach a response handler that watches for Meta Ad Library GraphQL traffic
5. Page Navigation – Load the Ad Library search URL for the given keyword and country
6. Scroll Loop – Repeatedly scroll the page to trigger additional GraphQL requests
7. GraphQL Interception – Capture and buffer every relevant network response as it streams in
8. Recursive Extraction – Parse each captured payload for ad snapshot objects at any nesting depth
9. Asset Parsing – Extract ad text, image URL, video URL, and CTA link from each ad object
10. Deduplication – Filter out duplicate ads by ID or text fingerprint
11. Item Cap Enforcement – Stop collecting once the configured maximum item count is reached
12. Dataset Push – Push all collected records from the run in a single batch

Key Benefits:

• Pull Meta Ad Library creative data for any keyword without manually browsing the library
• Capture raw ad data straight from the network layer instead of fragile HTML scraping
• Monitor competitor and industry advertising activity over time
• Feed creative research pipelines, swipe files, or competitive intelligence dashboards
• Automate recurring Meta Ad Library checks as new ad creatives go live

---

📥 Input

The Actor accepts the following input parameters:

Field	Type	Default	Description
searchKeyword	string	"shopify"	Keyword to search for within the Meta Ad Library.
countryCode	string	"US"	Two-letter country code to filter active ads by.
maxItems	integer	30	Maximum number of clean Meta Ad Library ad creatives to collect.
useApifyProxy	boolean	true	Enable Apify residential proxies.

Example Input:

{
  "searchKeyword": "fitness apparel",
  "countryCode": "US",
  "maxItems": 30,
  "useApifyProxy": true
}

Scrape Ads for a Single Keyword:

{
  "searchKeyword": "shopify"
}

Target a Different Country:

{
  "searchKeyword": "online courses",
  "countryCode": "GB",
  "maxItems": 50
}

---

📤 Output

The Actor pushes Meta Ad Library records with the following structure:

Field	Type	Description
ad_id	string	The unique ad archive ID from the Meta Ad Library
page_name	string	Name of the Facebook Page running the ad
ad_text	string	Primary ad copy/body text
image_url	string	URL of the ad's image creative, if present
video_url	string	URL of the ad's video creative, if present
cta_url	string	Destination link behind the ad's call-to-action

Example Meta Ad Library Record:

{
  "ad_id": "1234567890123456",
  "page_name": "Example Fitness Co.",
  "ad_text": "Get 20% off your first order — shop the new summer collection today.",
  "image_url": "https://scontent.xx.fbcdn.net/...",
  "video_url": "N/A",
  "cta_url": "https://examplefitness.com/shop"
}

---

🧰 Technical Stack

• Browser Automation: playwright (Chromium) for real, rendered access to the Meta Ad Library
• Network Interception: Playwright response listeners for capturing GraphQL traffic directly
• JSON Parsing: json with a recursive search algorithm for deeply nested ad objects
• URL Handling: urllib.parse for building the Ad Library search URL and parsing proxy URLs
• Async: asyncio for non-blocking browser interaction and scrolling
• Proxy: Apify Proxy with RESIDENTIAL configuration, wired into Playwright's launch options
• Logging: Apify Actor logging system
• Platform: Apify Actor serverless environment

---

📊 Data Fields Explained

Ad Identity

• ad_id: The unique archive identifier assigned by the Meta Ad Library
• page_name: The advertiser's Facebook Page name

Creative Content

• ad_text: The primary text/copy shown in the ad
• image_url: Direct link to the ad's image creative
• video_url: Direct link to the ad's video creative (HD preferred, SD fallback)

Conversion

• cta_url: The landing page URL behind the ad's call-to-action button

---

🎯 Use Cases

• Competitor Ad Monitoring – Track what ad creatives competitors are actively running
• Creative Research – Build swipe files of high-performing ad copy and creative formats
• Trend Analysis – Study messaging and creative trends across an industry or niche
• Market Entry Research – See what advertisers are already active in a target country
• Agency Reporting – Feed client competitive landscape reports with real ad data
• Academic Research – Study public advertising trends at scale
• Compliance Monitoring – Track how brands are positioning claims in live ad copy

---

🚀 Quick Start

1. Prepare Input

Go to Apify Console and enter:

{
  "searchKeyword": "shopify",
  "countryCode": "US"
}

2. Run the Actor

Click Start. The Actor will:

• Launch a headless browser and open the Meta Ad Library search results
• Intercept GraphQL network traffic as the page loads and scrolls
• Extract and deduplicate ad creatives from the captured data
• Push all results to the Dataset

3. Monitor Progress

Console shows:

[Meta Ad Scraper] Starting GraphQL Interceptor for keyword: 'shopify' (US)
Intercepted 12 raw ad record(s) from GraphQL stream!
Done! Successfully saved 30 clean ad creative(s) to dataset.

4. View & Download Results

• Results Tab: All Meta Ad Library records
• Export: JSON, CSV, Excel, or HTML
• Filter: By page name or ad ID
• API Access: Available via the Apify API

---

⚙️ Configuration

Single keyword search:

{
  "searchKeyword": "shopify"
}

Country-targeted search with item cap:

{
  "searchKeyword": "fashion",
  "countryCode": "CA",
  "maxItems": 100
}

Run without proxy:

{
  "searchKeyword": "shopify",
  "useApifyProxy": false
}

---

📈 Performance

Processing Speed

• One browser session per run, with 8 scroll cycles to trigger additional GraphQL requests
• ~2 seconds pause between each scroll to allow network requests to complete
• Slower than raw HTTP scraping since a full browser is launched, but necessary to trigger Meta's client-rendered GraphQL calls

Resource Usage

• Memory: Moderate to high, since a Chromium browser instance is launched and network traffic is buffered
• Network: Multiple GraphQL responses intercepted per scroll cycle
• Proxy: One residential proxy tunnel shared across the browser context for the run

---

⚠️ Important Notes

Legal & Compliance

• Fair Use: Respects the Meta Ad Library's public interface and applies scroll pacing to avoid overloading requests
• Public Data Only: Retrieves only publicly visible ad data exposed through the Ad Library's own network traffic
• Privacy: Collecting ad data may be subject to privacy regulations and Meta's Terms of Service — use only for legitimate purposes
• Legal: Not legal advice — consult qualified professionals before using this data for compliance-sensitive decisions

Data Quality

• Freshness: Reflects each Meta Ad Library ad's active state at time of run
• Completeness: Image, video, or CTA fields may return "N/A" if a given ad doesn't use that asset type
• Accuracy: Sourced directly from Meta's own GraphQL network responses
• Verification: Cross-check high-stakes creative details against the live Ad Library website

Best Practices

• Always configure a residential proxy for the most reliable Meta Ad Library access
• Use broader keywords (e.g., "fashion", "shop") if a narrow keyword returns no ads
• Re-run periodically to catch newly launched ad creatives
• Expect some fields to occasionally return "N/A" if that asset type isn't present on the ad
• Adjust maxItems based on how many scroll cycles are needed for a given keyword's ad volume

---

📄 License & Legal

Terms of Use:

• Use for legitimate research, marketing, and competitive analytics purposes
• Respect Meta's Terms of Service
• Do not use for unsolicited contact, harassment, or unlawful surveillance
• Use Meta Ad Library data responsibly and in compliance with applicable privacy laws

Disclaimer: Meta Ad Library Scraper is provided as-is for research and analytics purposes. Users are responsible for compliance with Meta's ToS and all applicable laws. This is not legal advice.

---

⚖️ Meta Ad Library Excellence

This Actor is optimized for Meta Ad Library research with:

• ✅ Real, browser-rendered GraphQL network interception
• ✅ Recursive parsing for maximum ad-object coverage
• ✅ Automation-detection evasion for more reliable access
• ✅ Deduplicated, clean creative output
• ✅ Real-time Dataset push
• ✅ Production-ready code