Facebook Ads Library Scraper

A powerful Apify Actor that scrapes Facebook Ads Library data at scale. Extract comprehensive ad information including ad content, metadata, spending data, reach estimates, and more from Facebook's public ad archive.

Why Choose Us?

• 🚀 Automatic Proxy Fallback: Intelligently handles Facebook's blocking with automatic fallback from no proxy → datacenter → residential proxy with retries
• 📊 Comprehensive Data Extraction: Captures all available ad data including images, videos, text, spending, reach estimates, and metadata
• 🌍 Multi-Country Support: Search ads from any country with simple country code configuration
• ⚡ Bulk Processing: Process multiple search queries simultaneously with bulk input support
• 🔄 Smart Pagination: Automatically handles pagination to collect all available ads
• 📝 Detailed Logging: Real-time progress updates and detailed error logging for transparency
• 🛡️ Robust Error Handling: Graceful handling of failures with automatic retries and fallbacks

Key Features

• Flexible Search Options: Search by keywords, URLs, or usernames with support for exact phrase or unordered keyword matching
• Advanced Filtering: Filter ads by active status, ad type (political, housing), media type (image, video, meme), and more
• Rich Data Extraction: Extract complete ad snapshots including:
  • Ad content (text, images, videos, captions)
  • Page information (name, profile picture, categories, like count)
  • Ad metadata (spend, reach estimate, currency, dates)
  • Targeting information (countries, political classifications)
  • Engagement data (CTA text, display format, publisher platform)
• Smart Proxy Management: Automatic proxy rotation and fallback to ensure successful scraping
• Scalable Architecture: Built on Apify's cloud infrastructure for reliable, scalable execution

Input

The actor accepts the following input parameters:

JSON Example

{
  "startUrls": [
    {
      "url": "linkedin"
    },
    {
      "url": "marketing tools"
    }
  ],
  "country": "US",
  "maxItems": 100,
  "activeStatus": "all",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "sortOrder": "relevancy_monthly_grouped",
  "maxComments": 0,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Input Parameters

Parameter	Type	Required	Default	Description
startUrls	Array	✅ Yes	-	List of search queries. Can be keywords, URLs, or usernames. Supports bulk input.
country	String	❌ No	"IN"	Two-letter country code (e.g., 'US', 'IN', 'AU', 'GB', 'CA') to filter ads by country.
maxItems	Integer	❌ No	50	Maximum number of ads to collect per search query (1-1000).
activeStatus	String	❌ No	"all"	Filter by ad active status. Options: "all", "active", "inactive".
adType	String	❌ No	"all"	Filter by ad type. Options: "all", "political", "housing".
mediaType	String	❌ No	"all"	Filter by media type. Options: "all", "image", "video", "meme".
searchType	String	❌ No	"keyword_unordered"	Type of search to perform. Options: "keyword_unordered", "keyword_exact_phrase".
sortOrder	String	❌ No	"relevancy_monthly_grouped"	Sort order for results. Options: "relevancy_monthly_grouped", "relevancy_all", "date_started_descending", "date_started_ascending".
maxComments	Integer	❌ No	0	Maximum number of comments to retrieve per ad (0-100).
proxyConfiguration	Object	❌ No	{"useApifyProxy": false}	Proxy configuration. By default, no proxy is used. The actor automatically falls back to datacenter proxy, then residential proxy if Facebook rejects requests.

Input Notes

• startUrls: Each item in the array should have a url or query field containing the search term
• country: Use ISO 3166-1 alpha-2 country codes (e.g., US, GB, CA, AU, IN)
• proxyConfiguration: If useApifyProxy is false, the actor starts with no proxy. If Facebook blocks the request, it automatically falls back to datacenter proxy, then residential proxy with 3 retries.

Output

The actor outputs structured JSON data for each scraped ad. All data is saved to the Apify dataset and can be exported in JSON, CSV, or Excel formats.

JSON Example

{
  "ad_archive_id": "1573731810659177",
  "page_id": "863706960159979",
  "snapshot": {
    "page_name": "Imelyy us.a",
    "page_profile_uri": "https://facebook.com/61582982529381",
    "page_profile_picture_url": "https://scontent.fdac142-1.fna.fbcdn.net/...",
    "page_categories": ["Men's Clothing"],
    "page_like_count": 0,
    "body": {
      "text": "🌟 Unveil the 2025 $50 Gold Eagle - Early Releases! 🌟..."
    },
    "caption": "2025-american-eagle-56.seri365co.com",
    "cta_text": "Shop now",
    "cta_type": "SHOP_NOW",
    "display_format": "VIDEO",
    "link_url": "https://2025-american-eagle-56.seri365co.com/",
    "images": [],
    "videos": [
      {
        "video_sd_url": "https://video.fdac142-1.fna.fbcdn.net/...",
        "video_preview_image_url": "https://scontent.fdac142-1.fna.fbcdn.net/..."
      }
    ]
  },
  "is_active": true,
  "currency": "",
  "spend": null,
  "reach_estimate": null,
  "start_date": 1762329600,
  "end_date": 1762416000,
  "start_date_formatted": "2025-11-05 00:00:00",
  "end_date_formatted": "2025-11-06 00:00:00",
  "publisher_platform": ["FACEBOOK"],
  "ad_library_url": "https://www.facebook.com/ads/library/?id=1573731810659177",
  "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&media_type=all&q=linkedin&search_type=keyword_unordered",
  "total": 1234,
  "ads_count": 100
}

Output Fields

Field	Type	Description
ad_archive_id	String	Unique identifier for the ad in Facebook's archive
page_id	String	Facebook page ID that published the ad
page_name	String	Name of the Facebook page
snapshot	Object	Complete ad snapshot containing all ad content and metadata
snapshot.body.text	String	Main text content of the ad
snapshot.caption	String	Ad caption text
snapshot.cta_text	String	Call-to-action button text
snapshot.images	Array	Array of image URLs in the ad
snapshot.videos	Array	Array of video objects with URLs
snapshot.page_categories	Array	Categories associated with the page
snapshot.page_like_count	Integer	Number of likes on the page
is_active	Boolean	Whether the ad is currently active
currency	String	Currency code for spending data
spend	Number	Amount spent on the ad (if available)
reach_estimate	Object	Estimated reach data
start_date	Integer	Unix timestamp of ad start date
end_date	Integer	Unix timestamp of ad end date
start_date_formatted	String	Human-readable start date
end_date_formatted	String	Human-readable end date
publisher_platform	Array	Platforms where ad was published (FACEBOOK, INSTAGRAM, etc.)
ad_library_url	String	Direct link to view the ad in Facebook Ads Library
url	String	Original search URL used to find this ad
total	Integer	Total number of ads found for the search query
ads_count	Integer	Number of ads collected in this run

🚀 How to Use the Actor (via Apify Console)

1. Log in to Apify Console: Go to https://console.apify.com and navigate to the Actors section.

2. Find the Actor: Search for "facebook-ads-library-scraper" or locate it in your actor list.

3. Configure Inputs:

   • startUrls: Add one or more search queries (keywords, URLs, or usernames)
   • country: Select the country code for filtering (e.g., US, GB, IN)
   • maxItems: Set the maximum number of ads to collect per search
   • Filters: Configure activeStatus, adType, mediaType, and searchType as needed
   • Proxy Configuration: Leave default (no proxy) or configure custom proxy settings

4. Run the Actor: Click the Start button to begin scraping.

5. Monitor Progress: Watch real-time logs to see:

   • Search progress for each query
   • Number of ads collected
   • Proxy fallback events (if any)
   • Any errors or warnings

6. Access Results: Once complete, go to the OUTPUT tab to:

   • View scraped ads in a table format
   • Export data as JSON, CSV, or Excel
   • Filter and sort results
   • Download individual ad details

7. Export Data: Click Export to download results in your preferred format.

Best Use Cases

• 📈 Competitive Intelligence: Monitor competitor ad strategies, messaging, and creative approaches
• 🎯 Market Research: Analyze ad trends, spending patterns, and targeting strategies in your industry
• 📊 Ad Performance Analysis: Study successful ad formats, CTAs, and content strategies
• 🔍 Brand Monitoring: Track ads mentioning your brand, competitors, or industry keywords
• 📱 Social Media Strategy: Research effective ad formats and content for your campaigns
• 🏛️ Political Ad Transparency: Monitor political advertising and spending disclosures
• 🏠 Housing Ad Compliance: Track housing-related ads for compliance monitoring
• 📚 Academic Research: Collect data for advertising, marketing, or social media research

Frequently Asked Questions

How does the proxy fallback work?

The actor starts with no proxy by default. If Facebook rejects or blocks a request (status codes 403, 429, 503), it automatically:

1. Falls back to a datacenter proxy
2. If that fails, falls back to a residential proxy with up to 3 retries
3. Once a proxy works, it continues using that proxy for all remaining requests

All proxy events are logged clearly in the actor logs.

Can I scrape ads from multiple countries?

Yes! You can run multiple actor runs with different country codes, or modify the code to process multiple countries in a single run.

What's the difference between keyword_unordered and keyword_exact_phrase?

• keyword_unordered: Finds ads containing all keywords in any order
• keyword_exact_phrase: Finds ads containing the exact phrase as specified

How many ads can I scrape?

The maxItems parameter allows you to collect up to 1,000 ads per search query. For larger datasets, run multiple searches or multiple actor runs.

Why are some fields null or empty?

Some ad data may not be available due to:

• Privacy settings on the ad
• Facebook's data availability policies
• Ad age or archival status
• Regional restrictions

How long does scraping take?

Scraping time depends on:

• Number of search queries
• Number of ads to collect per query
• Facebook's response times
• Whether proxy fallbacks occur

Typically, collecting 50 ads per query takes 1-3 minutes.

Can I scrape historical ads?

Yes! The actor can access Facebook's ad archive, which includes historical ads. Use the activeStatus filter to include inactive ads.

Is the data real-time?

The data comes from Facebook's Ads Library, which is updated regularly but may have a slight delay. The is_active field indicates whether an ad is currently running.

Support and Feedback

• Issues: Report bugs or issues through the Apify platform
• Feature Requests: Suggest improvements via the actor's page
• Documentation: Check the Apify documentation for platform-specific questions

Cautions

⚠️ Important Legal and Ethical Considerations:

• Public Data Only: This actor collects only publicly available data from Facebook's Ads Library. No private or password-protected content is accessed.

• Terms of Service: Ensure your use of this actor complies with:

  • Facebook's Terms of Service
  • Facebook's Ads Library Terms of Use
  • Apify's Terms of Service
  • Applicable local laws and regulations

• Rate Limiting: The actor includes built-in rate limiting and delays to respect Facebook's servers. Do not modify these settings to avoid potential blocks.

• Data Usage: You are responsible for:

  • Ensuring legal compliance with data protection laws (GDPR, CCPA, etc.)
  • Respecting privacy rights
  • Using scraped data ethically and legally
  • Not using data for spam, harassment, or illegal purposes

• No Warranty: Data accuracy and availability depend on Facebook's Ads Library. The actor provides no warranty on data completeness or accuracy.

• Respect Robots.txt: The actor respects Facebook's robots.txt and terms of service. Use responsibly and ethically.

---

Note: This actor is designed for legitimate research, competitive analysis, and transparency purposes. Always use scraped data responsibly and in compliance with applicable laws and regulations.