Facebook Ad Library Scraper

Comprehensive Meta ad library tool that fetches all ads for a given Facebook Ad Library URL or page URL. Extract ad creatives, copy, targeting info, and more from Meta's Ad Library.

🚀 Features

• Bulk URL Processing: Scrape multiple Ad Library URLs in one run
• Flexible Input: Accepts both direct Ad Library URLs and Facebook Page URLs
• Comprehensive Data Extraction: Retrieves all available ad data from Meta's Ad Library
• Real-time Processing: Live updates as each URL is processed
• Robust Error Handling: Detailed error reporting for failed requests
• Structured Output: Clean, organized results in dataset format

📋 Input Parameters

Field	Type	Required	Description
url	Array	Yes	List of Facebook Ad Library URLs or Page URLs to scrape

Example Input

{
    "url": [
        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&q=nike&search_type=keyword_unordered",
        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&view_all_page_id=123456789"
    ]
}

Supported URL Formats

1. Search Query URLs: Ad Library search results by keyword

   https://www.facebook.com/ads/library/?q=your_search_term&country=US
   

2. Page ID URLs: All ads from a specific Facebook Page

   https://www.facebook.com/ads/library/?view_all_page_id=PAGE_ID
   

3. Filtered URLs: Ad Library with specific filters applied

   https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=video
   

📤 Output Format

Each processed URL produces a detailed record in the dataset:

{
    "url": "https://www.facebook.com/ads/library/?q=example&country=US",
    "status": "completed",
    "result": {
        "ads": [...],
        "pageInfo": {...},
        "metadata": {...}
    },
    "success": true,
    "timestamp": "2024-01-15T10:30:00.000Z"
}

Output Fields

Field	Type	Description
url	String	The scraped Ad Library URL
status	String	Processing status: completed, error, or custom status from API
result	Object	The scraped ad data (structure depends on the ads found)
success	Boolean	Whether the scraping request succeeded
error	String	Error details (only present when success is false)
timestamp	String	ISO timestamp of when scraping was performed

🔧 Usage Example

Using Apify Client

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
    token: 'YOUR_APIFY_TOKEN',
});

// Run the Actor
const run = await client.actor('YOUR_USERNAME/facebook-ad-library-scraper').call({
    url: [
        'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=example'
    ]
});

// Fetch results
const { items } = await client.dataset(run.defaultDatasetId).listItems();

// Process results
items.forEach(item => {
    console.log(`URL: ${item.url}`);
    console.log(`Status: ${item.status}`);
    console.log(`Ads found:`, item.result);
});

Using Apify API

curl -X POST https://api.apify.com/v2/acts/YOUR_USERNAME~facebook-ad-library-scraper/runs \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=example"
    ]
  }'

Single URL Input

You can also pass a single URL as a string:

{
    "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=example"
}

🎯 Use Cases

• Competitor Analysis: Monitor competitors' ad strategies and creatives
• Market Research: Discover advertising trends in your industry
• Ad Creative Inspiration: Find successful ad formats and messaging
• Brand Monitoring: Track all ads mentioning your brand
• Political Ad Tracking: Monitor political advertising campaigns
• Transparency Research: Analyze advertising practices across industries
• Agency Intelligence: Gather insights for client pitches and strategies

⚡ Technical Details

Processing Flow

1. Actor receives array of Ad Library URLs from input
2. Each URL is processed sequentially with a separate API call
3. Results are saved individually as they're processed
4. Final summary shows total processed, successful, and failed requests

API Integration

• Endpoint: Secure webhook-based scraping service
• Method: POST
• Content-Type: application/json
• Timeout: 2 minutes per URL (to handle complex pages)

Performance

• Memory: 128-512 MB
• Processing Speed: Varies based on ad volume per URL
• Recommended Batch Size: Up to 50 URLs per run
• Runtime: Scales with number of URLs and ads per page

🛡️ Error Handling

The Actor handles various error scenarios:

• ✅ Invalid URL format detection
• ✅ Network timeout handling (2-minute timeout)
• ✅ API connection errors
• ✅ Missing required fields validation
• ✅ Webhook failures with detailed error messages
• ✅ Individual URL failures don't stop batch processing

📈 Results Summary

At the end of each run, you'll receive a summary log:

Processing complete. Total: 10, Successful: 9, Failed: 1

Each failed request includes detailed error information in the output.

🔍 Output Views

The Actor provides a convenient Overview view in the Apify Console showing:

• Ad Library URL (clickable link)
• Processing status
• Scraped data preview
• Success indicator
• Error details (if any)
• Timestamp

💡 Best Practices

1. URL Validation: Ensure your URLs are properly formatted Facebook Ad Library URLs
2. Batch Processing: Group URLs in batches of 10-50 for optimal performance
3. Error Handling: Check the success field before processing results
4. Rate Awareness: Be mindful of request volumes to avoid rate limiting
5. Country Codes: Use valid ISO country codes in your Ad Library URLs

🌍 Supported Countries

Facebook Ad Library supports ads from over 200 countries. Use the appropriate ISO country code in your URL:

• US - United States
• GB - United Kingdom
• CA - Canada
• AU - Australia
• DE - Germany
• And many more...

📚 Integration Examples

Filter Successful Results Only

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const successfulResults = items.filter(item => item.success);
console.log('Successfully scraped:', successfulResults.length, 'URLs');

Export Results to CSV

// Get dataset items in CSV format
const csvUrl = `https://api.apify.com/v2/datasets/${run.defaultDatasetId}/items?format=csv`;
// Download or process CSV as needed

Webhook Integration

Set up a webhook to receive results automatically when the Actor finishes:

const run = await client.actor('YOUR_USERNAME/facebook-ad-library-scraper').call(
    { url: [...] },
    { webhooks: [{ eventTypes: ['ACTOR.RUN.SUCCEEDED'], requestUrl: 'YOUR_WEBHOOK_URL' }] }
);

🔐 Privacy & Compliance

• Only scrapes publicly available data from Meta's Ad Library
• Respects Meta's Terms of Service and data access policies
• Results are stored in your private Apify dataset
• No personal data is collected beyond what's publicly available in Ad Library

⚠️ Limitations

• Only scrapes publicly visible ads in Meta's Ad Library
• Subject to Meta's Ad Library availability and access policies
• Large result sets may take longer to process
• Some ad details may not be available for all ad types

🆘 Support

Need help or have questions?

• 📝 Create an issue in the Actor repository
• 💬 Contact Apify support for platform-related questions

---

Version: 0.0.1
Last Updated: January 2026

🌟 Get Started

Ready to scrape Facebook Ad Library? Run this Actor now or integrate it into your workflow with the Apify API!