Facebook Ad Library Scraper 2.0

A powerful Apify actor that scrapes ads from the Facebook Ad Library with advanced features like country selection, active status filtering, and intelligent fallback search.

Features

• ✅ Multi-Country Support: Scrape ads from 247+ countries
• ✅ Three Search Modes: Keyword search, first suggestion, or direct Facebook URL/page ID
• ✅ Flexible Input: Mix and match URLs, page IDs, and keywords in bulk
• ✅ Smart Fallback Search: Automatically finds similar pages when keyword search returns no results
• ✅ Duplicate Detection: Prevents duplicate ads using ad_id tracking
• ✅ Active Status Filtering: Filter by ALL, ACTIVE, or INACTIVE ads
• ✅ Rich Data Extraction: Extracts carousel cards, videos, images, and targeting info
• ✅ Real-time Data Push: Ads are saved immediately as they're found
• ✅ Residential Proxy Support: Works with Apify's residential proxies for reliable scraping

Search Modes

1. Keyword Search (Default)

Standard keyword search with intelligent fallback:

{
  "searchTerms": ["Nike", "Adidas"],
  "searchMode": "keyword",
  "countryCode": "US",
  "maxAds": 100
}

2. First Suggestion (Smart)

Uses first Typeahead API suggestion - perfect for brand pages:

{
  "searchTerms": ["Tesla", "SpaceX"],
  "searchMode": "first_suggestion",
  "countryCode": "DE",
  "maxAds": 50
}

3. Facebook URL/ID Direct

Fastest method - scrape directly from page URLs or IDs:

{
  "searchTerms": [
    "https://www.facebook.com/UnderArmour",
    "8741241286",
    "https://www.facebook.com/Nike",
    "15087023444"
  ],
  "searchMode": "facebook_url",
  "countryCode": "US",
  "maxAds": 200
}

Note: You can mix URLs and page IDs in the same array for bulk scraping!

Input Parameters

{
  "searchTerms": ["Nike", "marketing"],
  "searchMode": "keyword",
  "countryCode": "DE",
  "adActiveStatus": "ACTIVE",
  "maxAds": 200,
  "enableSimilarSearch": true,
  "maxSimilarPages": 3,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Parameters

Parameter	Type	Default	Description
searchTerms	Array	Required	Keywords, page names, Facebook URLs, or page IDs
searchMode	String	"keyword"	How to search: "keyword", "first_suggestion", or "facebook_url"
countryCode	String	"ALL"	ISO 2-letter country code or "ALL" for all countries
adActiveStatus	String	"ALL"	Filter by ad status: "ALL", "ACTIVE", or "INACTIVE"
maxAds	Integer	100	Maximum number of ads to scrape per search term (1-5000)
enableSimilarSearch	Boolean	true	Enable fallback to similar pages when keyword returns no results
maxSimilarPages	Integer	1	Number of similar pages to try (1-5)
debugMode	Boolean	false	Enable verbose logging

Output Format

Each ad is saved as a separate dataset item with the following structure:

{
  "ad_id": "1234567890",
  "status": "ACTIVE",
  "page_name": "Nike",
  "page_id": "123456789",
  "start_date": "2025-11-28",
  "end_date": "2025-11-28",
  "creative": {
    "body": "Ad text content...",
    "cta_type": "SHOP_NOW",
    "cta_text": "Shop now",
    "link_url": "https://example.com",
    "images": ["https://..."],
    "videos": ["https://..."],
    "cards": []
  },
  "targeting": {
    "reach_estimate": null,
    "info": null
  },
  "currency": "USD",
  "spend": null,
  "impressions": {
    "impressions_text": "10K-50K",
    "impressions_index": 3
  },
  "publisher_platforms": ["FACEBOOK", "INSTAGRAM"]
}

How It Works

1. Token Extraction: Uses Playwright to extract authentication tokens from Facebook
2. GraphQL API: Makes direct GraphQL requests for fast, efficient data retrieval
3. Smart Fallback: If keyword search fails, queries the Typeahead API for related pages
4. Duplicate Prevention: Tracks ad_id to ensure each ad is only saved once
5. Real-time Saving: Pushes ads to the dataset immediately as they're found

Use Cases

• Competitive Analysis: Monitor competitors' ad strategies
• Market Research: Discover trending ad creatives in your industry
• Ad Inspiration: Find successful ad formats and messaging
• Brand Monitoring: Track how brands are advertising across different countries
• Academic Research: Study advertising patterns and trends

Limitations

• Requires Apify residential proxies for reliable operation
• Rate limited by Facebook's API
• Some ad fields may be null depending on ad type and status
• Timeframe limited to ads currently in Facebook Ad Library

Performance

• Typically scrapes 30-50 ads per minute
• Handles up to 5000 ads per search term
• Supports multiple search terms in a single run
• Automatic retry with fallback search if initial query fails

Author

Built with ❤️ for the Apify community

Version

Current version: 0.1.12

License

Apache-2.0