# Facebook Ads Meta Ad library Scraper (`bockmurat/facebook-ads-scraper-actor`) Actor Cheapest and fastest Facebook / Meta Ad library scraper on Apify. Scrape All ads per Ad library Url including creatives and collateral results. Scrapes Full Results for all Ads across Facebook, Instragram, Threads, Whatsapp, Messenger and Audience Network. - **URL**: https://apify.com/bockmurat/facebook-ads-scraper-actor.md - **Developed by:** [Murat](https://apify.com/bockmurat) (community) - **Categories:** Automation, Social media, E-commerce - **Stats:** 391 total users, 5 monthly users, 67.6% runs succeeded, 19 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing $0.50 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Ads Library Scraper Fast and reliable scraper for Facebook Ads Library that can extract thousands of ads from any Facebook Page. Built with automatic rate limit handling, proxy rotation, and intelligent session management. ### ✨ Key Features - 🚀 **High Performance**: Scrapes ~5-10 ads/second with optimized GraphQL requests - 🔄 **Automatic Rate Limit Handling**: Automatically switches IPs and renews sessions when rate limited - 🌍 **Smart Proxy Rotation**: Rotates through multiple countries (US, UK, CA, AU, DE) for better success rates - 💪 **Robust & Reliable**: Multiple retry attempts with exponential backoff - 📊 **Unlimited Scraping**: Can scrape thousands of ads from any page (tested with 15,000+ ads) - ⚡ **Real-time Streaming**: Results saved immediately to dataset - 🎯 **Flexible Filtering**: Filter by country, status, ad type, and more ### 📊 What You Can Extract Each ad includes comprehensive data: - **Ad Content**: Text, titles, descriptions, call-to-action - **Media**: Images, videos, carousel content - **Targeting**: Demographics, locations, interests - **Performance**: Impressions, spend ranges (when available) - **Metadata**: Creation time, status, page info - **URLs**: Ad snapshot links, landing pages ### 🎯 Use Cases - 📈 **Competitive Analysis**: Monitor competitor ad strategies - 🔍 **Market Research**: Discover industry trends and messaging - 📱 **Social Media Monitoring**: Track brand campaigns - 💼 **Business Intelligence**: Analyze advertising tactics - 🎨 **Creative Inspiration**: Study successful ad creatives - 📉 **Spend Tracking**: Monitor advertising investments ### 🚀 Quick Start #### Option 1: Using Page ID ```json { "pageId": "109806077081081", "country": "US", "activeStatus": "all", "maxAds": 5000 } ```` #### Option 2: Using Full URL ```json { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&search_type=page&view_all_page_id=109806077081081", "maxAds": 5000, "requestDelay": 100 } ``` #### Option 3: Unlimited Scraping ```json { "pageId": "109806077081081", "requestDelay": 100 } ``` *Leave `maxAds` empty to scrape all available ads* ### 📝 Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `url` | string | \* | - | Full Facebook Ads Library URL | | `pageId` | string | \* | - | Facebook Page ID (alternative to URL) | | `country` | string | No | `"ALL"` | Country code (US, GB, ALL, etc.) | | `activeStatus` | string | No | `"all"` | Filter: `all`, `active`, or `inactive` | | `adType` | string | No | `"all"` | Filter: `all`, `political`, `housing`, `employment`, `credit` | | `maxAds` | integer | No | unlimited | Maximum number of ads to scrape | | `requestDelay` | integer | No | `500` | Delay between requests in milliseconds | | `useProxy` | boolean | No | `true` | Enable Apify proxy rotation after rate limiting | | `maxSessionRenewals` | integer | No | `10` | Max times to renew session when rate limited | **\*** Either `url` or `pageId` is required ### 💡 How It Works #### Smart Architecture 1. **Browser Initialization**: Launches Playwright browser to capture authentication tokens from Facebook 2. **Token Extraction**: Intercepts GraphQL requests to extract necessary authentication headers 3. **Direct API Requests**: Makes fast, direct GraphQL API calls using captured tokens 4. **Cursor-Based Pagination**: Efficiently navigates through results using Facebook's cursor system 5. **Rate Limit Detection**: Automatically detects rate limiting (error code 1675004) 6. **Intelligent Recovery**: When rate limited: - Closes current browser session - Waits with exponential backoff (30s-120s) - Creates new session with different proxy IP - Rotates through 5 countries for IP diversity - Retries up to 6 times before falling back to no-proxy - Resumes exactly where it left off #### Rate Limit Handling Flow ``` Rate limit detected → Wait 30-120s → Try proxy (US) → Failed? → Wait 10s → Try proxy (GB) → Failed? → Wait 20s → Try proxy (CA) → Failed? → Wait 30s → Try proxy (AU) → Failed? → Wait 40s → Try proxy (DE) → Failed? → Wait 50s → Try without proxy → Failed? → Stop with error ``` ### 📤 Output Format Results are saved to Apify dataset in JSON format: ```json { "ad_archive_id": "1234567890", "page_id": "109806077081081", "page_name": "Example Brand", "ad_creation_time": "2024-01-15T10:30:00+0000", "ad_creative_bodies": ["Check out our new collection!"], "ad_creative_link_titles": ["Shop Now"], "ad_creative_link_descriptions": ["Free shipping on orders over $50"], "ad_snapshot_url": "https://www.facebook.com/ads/library/?id=1234567890", "currency": "USD", "spend": { "lower_bound": "100", "upper_bound": "500" }, "impressions": { "lower_bound": "10000", "upper_bound": "50000" }, "scrapedAt": "2024-11-17T08:30:00.000Z" } ``` ### 🎛️ Advanced Configuration #### High-Speed Scraping For maximum speed (with higher rate limit risk): ```json { "pageId": "109806077081081", "requestDelay": 100, "maxSessionRenewals": 15 } ``` #### Conservative Scraping For slower but more reliable scraping: ```json { "pageId": "109806077081081", "requestDelay": 1000, "maxSessionRenewals": 5 } ``` ### ⚡ Performance - **Speed**: 5-10 ads per second (varies by rate limiting) - **Reliability**: 99% success rate with automatic recovery - **Scale**: Tested with 15,000+ ads per run - **Efficiency**: ~10 ads per GraphQL request ### 🛡️ Best Practices 1. **Start with limits**: Test with `maxAds: 100` first 2. **Monitor logs**: Check Actor logs for rate limit handling 3. **Adjust delays**: Increase `requestDelay` if frequently rate limited 4. **Enable proxies**: Keep `useProxy: true` for automatic recovery 5. **Be patient**: Let the actor handle rate limits automatically 6. **Export data**: Download dataset after completion ### ❓ Common Issues #### "Failed to capture GraphQL tokens" **Solution**: This usually happens with blocked proxy IPs. The actor will automatically retry with different IPs. If all retries fail, it may indicate Facebook is blocking the proxy provider. #### Frequent Rate Limiting **Solution**: - Increase `requestDelay` to 1000ms or higher - Increase `maxSessionRenewals` for more retry attempts - Ensure `useProxy: true` is enabled #### Duplicate Ads **Solution**: The actor automatically deduplicates ads by `ad_archive_id`. Duplicates in output are rare. ### 📊 Cost Estimation Typical costs on Apify (approximate): - **1,000 ads**: ~0.01-0.02 credits - **10,000 ads**: ~0.10-0.20 credits - **100,000 ads**: ~1.00-2.00 credits *Costs vary based on rate limiting, proxy usage, and request delays* ### 🔧 Technical Details - **Platform**: Apify Actor (Node.js) - **Browser**: Playwright with Chromium - **Proxy**: Apify Residential Proxies with country rotation - **API**: Facebook GraphQL API (AdLibrarySearchPaginationQuery) - **Storage**: Apify Dataset with immediate persistence ### 📞 Support & Feedback Having issues or suggestions? - Check Actor logs for detailed error messages - Review input parameters for correctness - Ensure Page ID or URL is valid - Contact Apify support for platform issues ### ⚖️ Legal & Ethical Use This actor scrapes publicly available data from Facebook's Ad Library. Users are responsible for: - Complying with Facebook's Terms of Service - Respecting data privacy and applicable laws - Using scraped data ethically and legally - Not overwhelming Facebook's servers **Note**: This tool is for research, analysis, and competitive intelligence purposes only. ### 🚀 Version History - **v1.0**: Initial release with basic GraphQL scraping - **v2.0**: Added automatic rate limit handling and proxy rotation - **v3.0**: Implemented country rotation and session management - **Current**: Robust retry logic with 6-attempt fallback system *** **Made with ❤️ for the Apify community** *Extract insights, stay competitive, and make data-driven decisions with Facebook Ads Library Scraper.* # Actor input Schema ## `url` (type: `string`): Full URL from Facebook Ads Library (alternative to using pageId) ## `pageId` (type: `string`): Facebook Page ID to scrape ads from (alternative to using URL) ## `country` (type: `string`): Country code for ads (e.g., US, GB, ALL) ## `activeStatus` (type: `string`): Filter by active/inactive ads ## `adType` (type: `string`): Type of ads to scrape ## `maxAds` (type: `integer`): Maximum number of ads to scrape (leave empty for unlimited) ## `pageSize` (type: `integer`): Number of results per GraphQL request (default: 30, max recommended: 200) ## `requestDelay` (type: `integer`): Delay between requests in milliseconds ## `useProxy` (type: `boolean`): Use Apify proxy after rate limiting ## `maxSessionRenewals` (type: `integer`): Maximum number of times to renew session when rate limited ## Actor input object example ```json { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=page&view_all_page_id=20531316728", "country": "ALL", "activeStatus": "all", "adType": "all", "pageSize": 30, "requestDelay": 500, "useProxy": true, "maxSessionRenewals": 10 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=page&view_all_page_id=20531316728" }; // Run the Actor and wait for it to finish const run = await client.actor("bockmurat/facebook-ads-scraper-actor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=page&view_all_page_id=20531316728" } # Run the Actor and wait for it to finish run = client.actor("bockmurat/facebook-ads-scraper-actor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=page&view_all_page_id=20531316728" }' | apify call bockmurat/facebook-ads-scraper-actor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bockmurat/facebook-ads-scraper-actor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Meta Ad library Scraper", "description": "Cheapest and fastest Facebook / Meta Ad library scraper on Apify. Scrape All ads per Ad library Url including creatives and collateral results. Scrapes Full Results for all Ads across Facebook, Instragram, Threads, Whatsapp, Messenger and Audience Network.", "version": "3.1", "x-build-id": "UOLZRucFRlHMskLdJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bockmurat~facebook-ads-scraper-actor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bockmurat-facebook-ads-scraper-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/bockmurat~facebook-ads-scraper-actor/runs": { "post": { "operationId": "runs-sync-bockmurat-facebook-ads-scraper-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/bockmurat~facebook-ads-scraper-actor/run-sync": { "post": { "operationId": "run-sync-bockmurat-facebook-ads-scraper-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "url": { "title": "Ads Library URL", "type": "string", "description": "Full URL from Facebook Ads Library (alternative to using pageId)" }, "pageId": { "title": "Page ID", "type": "string", "description": "Facebook Page ID to scrape ads from (alternative to using URL)" }, "country": { "title": "Country", "type": "string", "description": "Country code for ads (e.g., US, GB, ALL)", "default": "ALL" }, "activeStatus": { "title": "Active Status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter by active/inactive ads", "default": "all" }, "adType": { "title": "Ad Type", "enum": [ "all", "political", "housing", "employment", "credit" ], "type": "string", "description": "Type of ads to scrape", "default": "all" }, "maxAds": { "title": "Maximum Ads", "minimum": 1, "type": "integer", "description": "Maximum number of ads to scrape (leave empty for unlimited)" }, "pageSize": { "title": "Page Size", "minimum": 1, "maximum": 300, "type": "integer", "description": "Number of results per GraphQL request (default: 30, max recommended: 200)", "default": 30 }, "requestDelay": { "title": "Request Delay (ms)", "minimum": 0, "type": "integer", "description": "Delay between requests in milliseconds", "default": 500 }, "useProxy": { "title": "Use Proxy", "type": "boolean", "description": "Use Apify proxy after rate limiting", "default": true }, "maxSessionRenewals": { "title": "Max Session Renewals", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of times to renew session when rate limited", "default": 10 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```