# Facebook Ads Library (`data_xplorer/facebook-ads-library`) Actor 🧲 Scrape Facebook Ad Library at scale. Extract ads, creatives, videos, CTAs, links & platforms. Enable Ad Details for EU reach, demographics & audience targeting. Multi-URL, auto-pagination, MCP ready. - **URL**: https://apify.com/data\_xplorer/facebook-ads-library.md - **Developed by:** [Data Xplorer](https://apify.com/data_xplorer) (community) - **Categories:** Automation, Developer tools, Lead generation - **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.50 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Ad Library Scraper Unlock the full power of Meta's Ad Library with our advanced scraper! Monitor competitor ads, analyze creative strategies, track ad spend transparency, and get detailed demographic insights — all structured and ready for analysis. ![Facebook Ad Library Scraper](https://i.ibb.co/8DhzvFwp/fil-07-TSt-Oh-La9yr-LFz-O.jpg) ### 💎 Why Choose Our Facebook Ad Library Scraper? - 🚀 **Fast & Reliable**: Advanced extraction engine for consistent, high-quality results - 📊 **Complete Ad Data**: Creative content, images, videos, CTAs, links, platforms, and publication dates - 🔬 **Ad Details Mode**: Unlock reach, demographics, age/gender breakdowns, and targeting data (optional) - 📄 **Auto-Pagination**: Automatically fetches all pages of results — no manual scrolling needed - 🎯 **Multi-URL Support**: Scrape multiple pages or search queries in a single run - 🖼️ **Smart Media Extraction**: Images, video thumbnails, HD/SD video URLs from all ad formats - 🛡️ **Residential Proxy Support**: Built-in anti-detection for reliable access - 🤖 **MCP Compatible**: Use with AI agents via Apify's MCP Server integration ### 🔮 How It Works #### 1. 🔗 **Provide Ad Library URLs** Paste one or more Facebook Ad Library URLs. You can scrape: - **A specific page's ads** — Use `view_all_page_id` parameter - **Search results** — Use `q` parameter for keyword search - **Filtered results** — Active/inactive, country, media type #### 2. 📦 **Set Your Limits** Choose how many ads to scrape (default: 100, set 0 for unlimited). #### 3. 🔬 **Enable Ad Details** (Optional) Turn on **Fetch Ad Details** to enrich each ad with: - 📈 EU total reach - 👥 Demographic breakdowns (age × gender × country) - 🎯 Audience targeting (age range, gender, locations) - 💼 Payer & beneficiary transparency data #### 4. ⚡ **Run & Export** Results are pushed incrementally — you can start using the data before the run completes. Export to JSON, CSV, Excel, or connect via API. ### ✨ What You'll Get #### 📋 Standard Fields (Always Included) | Field | Description | |-------|-------------| | `adArchiveId` | Unique Facebook Ad Library ID | | `collationId` | Groups ad variations together | | `pageName` | Advertiser page name | | `image` | Preview image URL (or video thumbnail) | | `bodyText` | Ad copy / body text | | `title` | Ad title | | `publicationDate` | Start & end dates with timestamps | | `adVariations` | Number of creative variations | | `ctaText` | Call-to-action button text (Learn More, Shop Now, etc.) | | `linkUrl` | Destination URL | | `isActive` | Whether the ad is currently running | | `hasVideo` | Whether the ad contains video | | `platforms` | Distribution platforms (Facebook, Instagram, Messenger, Audience Network) | | `mediaType` | IMAGE, VIDEO, or TEXT | | `all_images` | All image URLs found in the ad | | `all_videos` | All video URLs (HD/SD) | #### 🔬 Detail Fields (When Fetch Ad Details Is Enabled) | Field | Description | |-------|-------------| | `audience` | Targeting info: gender, age range (min/max), locations | | `reach` | Total EU reach + breakdown by country, age range, and gender | | `payer` | Entity paying for the ad | | `beneficiary` | Entity benefiting from the ad | ### 📋 Quick Start #### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `urls` | array | — | One or more Facebook Ad Library URLs to scrape | | `maxAds` | number | `100` | Maximum ads to scrape (0 = unlimited) | | `fetchDetails` | boolean | `false` | Fetch detailed reach, demographics & targeting per ad | | `proxyConfig` | object | Residential | Proxy configuration (residential recommended) | #### Input Example — Scrape a Page's Ads ```json { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=FR&view_all_page_id=434174436675167&media_type=all" } ], "maxAds": 100, "fetchDetails": false } ```` #### Input Example — Search by Keyword ```json { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=running%20shoes&media_type=all" } ], "maxAds": 50, "fetchDetails": false } ``` #### Input Example — With Ad Details (Reach & Demographics) ```json { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=FR&view_all_page_id=434174436675167&media_type=all" } ], "maxAds": 30, "fetchDetails": true } ``` #### Input Example — Multiple Pages ```json { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=FR&view_all_page_id=434174436675167&media_type=all" }, { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&view_all_page_id=139594698297&media_type=all" } ], "maxAds": 200, "fetchDetails": false } ``` #### Output Example — Standard ```json { "adArchiveId": "1472608967817658", "collationId": "8293741056382", "pageName": "Apple", "image": "https://scontent.xx.fbcdn.net/v/t45.1600-4/...", "bodyText": "iPhone 16 Pro. The thinnest borders ever on iPhone.", "title": "iPhone 16 Pro", "publicationDate": { "startDate": "2026-04-15T00:00:00.000Z", "endDate": "N/A", "startDate_timestamp": 1776384000, "endDate_timestamp": 0 }, "adVariations": 3, "ctaText": "Learn More", "linkUrl": "https://www.apple.com/iphone-16-pro/", "isActive": true, "hasVideo": true, "platforms": ["Facebook", "Instagram"], "mediaType": "VIDEO", "all_images": [], "all_videos": ["https://video.xx.fbcdn.net/v/..."] } ``` #### Output Example — With Ad Details ```json { "adArchiveId": "1472608967817658", "collationId": "8293741056382", "pageName": "Apple", "image": "https://scontent.xx.fbcdn.net/v/t45.1600-4/...", "bodyText": "iPhone 16 Pro. The thinnest borders ever on iPhone.", "title": "iPhone 16 Pro", "publicationDate": { "startDate": "2026-04-15T00:00:00.000Z", "endDate": "N/A", "startDate_timestamp": 1776384000, "endDate_timestamp": 0 }, "adVariations": 3, "ctaText": "Learn More", "linkUrl": "https://www.apple.com/iphone-16-pro/", "isActive": true, "hasVideo": true, "platforms": ["Facebook", "Instagram"], "mediaType": "VIDEO", "audience": { "gender": "All", "age": { "min": 18, "max": 65 }, "locations": [ { "name": "France", "type": "countries", "excluded": false } ] }, "reach": { "total": 1665288, "breakdown": [ { "country": "FR", "age_range": "18-24", "male": 96974, "female": 170035, "unknown": 21102 }, { "country": "FR", "age_range": "25-34", "male": 252206, "female": 367860, "unknown": 30821 }, { "country": "FR", "age_range": "35-44", "male": 118744, "female": 196991, "unknown": 19212 }, { "country": "FR", "age_range": "45-54", "male": 62221, "female": 123529, "unknown": 12105 }, { "country": "FR", "age_range": "55-64", "male": 39991, "female": 81678, "unknown": 6396 }, { "country": "FR", "age_range": "65+", "male": 41720, "female": 85028, "unknown": 4527 } ] }, "payer": "APPLE INC.", "beneficiary": "APPLE INC." } ``` ### 🔗 Integrations Connect this scraper to your favorite tools and automate your ad intelligence workflows: - 🔄 **N8N** — [Apify + N8N Integration Guide](https://docs.apify.com/platform/integrations/n8n) - ⚡ **Make (Integromat)** — [Apify + Make Integration Guide](https://docs.apify.com/platform/integrations/make) - 🐍 **Python** — [Apify Python Client](https://docs.apify.com/api/client/python) - 📦 **Node.js** — [Apify JavaScript Client](https://docs.apify.com/api/client/js) - 🤖 **MCP (AI Agents)** — [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp) - 📊 **Google Sheets** — [Apify + Google Sheets](https://docs.apify.com/platform/integrations/google-sheets) - 🗄️ **Webhooks** — [Apify Webhooks](https://docs.apify.com/platform/integrations/webhooks) #### 🤖 MCP Server for AI Agents Use this scraper as a tool for Claude, ChatGPT, or any AI agent via the [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp). Your AI assistant can: - Monitor competitor ad strategies automatically - Analyze creative trends across industries - Generate reports from ad library data - Track new ads from specific brands in real-time ### 🎯 Use Cases #### 📱 **Competitor Intelligence** - Monitor what ads your competitors are running right now - Track their creative strategies over time - Analyze which platforms they target (Facebook vs. Instagram) - Compare ad copy, CTAs, and landing pages #### 📊 **Media Buying & Planning** - Discover which demographics competitors are targeting - Analyze reach distribution across age groups and genders - Identify underserved audience segments - Benchmark your reach against competitors #### 🎨 **Creative Strategy** - Build a swipe file of competitor ad creatives - Analyze which ad formats perform best (image vs. video) - Track seasonal creative trends - Study CTA and messaging patterns #### 🏢 **Brand Safety & Compliance** - Monitor who is running ads mentioning your brand - Track payer/beneficiary transparency data - Audit ad compliance across markets - Detect unauthorized use of brand assets #### 📈 **Market Research** - Analyze advertising trends in specific industries - Compare ad strategies across countries - Study seasonal advertising patterns - Export data for custom analysis in Excel, Tableau, or PowerBI #### 🤖 **AI-Powered Workflows** - Feed ad data into LLMs for creative analysis - Automate weekly competitor ad reports - Build custom dashboards with real-time ad monitoring - Use MCP integration for conversational ad intelligence ### 💡 Pro Tips #### 🔥 **For Competitive Analysis** Use `view_all_page_id` to scrape all ads from a specific competitor page. Find the page ID by searching for the brand on Facebook Ad Library and checking the URL. #### 📈 **For Demographic Insights** Enable `fetchDetails: true` to get the full demographic breakdown. This reveals exactly which age groups and genders the advertiser is reaching — invaluable for media planning. #### 🌍 **For Multi-Market Analysis** Create multiple URLs with different `country` parameters to compare how the same brand advertises differently across markets. #### ⚡ **For Maximum Speed** Keep `fetchDetails: false` for fast bulk scraping. Only enable details when you specifically need reach and demographic data. #### 💰 **For Cost Optimization** Set `maxAds` to limit costs. Start with a small number to validate your query, then increase for full scrapes. #### 🔄 **For Ongoing Monitoring** Schedule this scraper to run daily or weekly via Apify Schedules. Combine with webhooks to get notified when new ads are detected. ### 🤝 Support & Resources Need help? Have questions? We're here to help! If you encounter any issues or have feature requests, please don't hesitate to open an issue. **❤️ Love our scraper?** Please leave a review — it helps us build better tools! *** **Built with ❤️ for marketers, media buyers, and competitive intelligence professionals** # Actor input Schema ## `urls` (type: `array`): List of Facebook Ad Library URLs to scrape. ## `maxAds` (type: `integer`): Maximum number of ads to scrape per URL. Set 0 for unlimited. ## `fetchDetails` (type: `boolean`): Fetch detailed targeting data (audience, reach, demographics) for each ad. Adds extra API calls. ## `proxyConfig` (type: `object`): Proxy settings. ## Actor input object example ```json { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=FR&view_all_page_id=434174436675167" } ], "maxAds": 100, "fetchDetails": false, "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `ads` (type: `string`): All scraped ads with images, videos, dates, CTA, platforms and extra details # 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 = { "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=FR&view_all_page_id=434174436675167" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("data_xplorer/facebook-ads-library").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 = { "urls": [{ "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=FR&view_all_page_id=434174436675167" }] } # Run the Actor and wait for it to finish run = client.actor("data_xplorer/facebook-ads-library").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 '{ "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=FR&view_all_page_id=434174436675167" } ] }' | apify call data_xplorer/facebook-ads-library --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=data_xplorer/facebook-ads-library", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library", "description": "🧲 Scrape Facebook Ad Library at scale. Extract ads, creatives, videos, CTAs, links & platforms. Enable Ad Details for EU reach, demographics & audience targeting. Multi-URL, auto-pagination, MCP ready.", "version": "0.5", "x-build-id": "smD6ajbQyDmC5tht3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/data_xplorer~facebook-ads-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-data_xplorer-facebook-ads-library", "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/data_xplorer~facebook-ads-library/runs": { "post": { "operationId": "runs-sync-data_xplorer-facebook-ads-library", "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/data_xplorer~facebook-ads-library/run-sync": { "post": { "operationId": "run-sync-data_xplorer-facebook-ads-library", "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", "required": [ "urls" ], "properties": { "urls": { "title": "Ad Library URLs", "type": "array", "description": "List of Facebook Ad Library URLs to scrape.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxAds": { "title": "Max Ads per URL", "minimum": 0, "type": "integer", "description": "Maximum number of ads to scrape per URL. Set 0 for unlimited.", "default": 100 }, "fetchDetails": { "title": "Fetch Ad Details", "type": "boolean", "description": "Fetch detailed targeting data (audience, reach, demographics) for each ad. Adds extra API calls.", "default": false }, "proxyConfig": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```