# 📢 Facebook Ads Scraper — Competitor Ad Tracker (`nexgendata/facebook-ads-library-scraper`) Actor Scrape Meta's Ad Library for active Facebook and Instagram ads. Track competitor ad creatives, spend estimates, targeting, and campaign duration. Essential for ad intelligence and competitive research. - **URL**: https://apify.com/nexgendata/facebook-ads-library-scraper.md - **Developed by:** [Stephan Corbeil](https://apify.com/nexgendata) (community) - **Categories:** Marketing, Social media, E-commerce - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $0.50 / 1,000 ad extracteds 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 & Competitor Ad Tracker Track what your competitors are running on Facebook and Instagram. Extract ad creatives, copy, landing pages, CTAs, spend data, and video assets from Meta's public Ad Library — then get an automated competitive analysis with advertiser breakdowns and strategic insights. ### Two ways to use it **Competitor Tracker mode** (default) — Get an enriched competitive report. The first row of your output is a summary with advertiser profiles, ad age analysis, creative type breakdown (video vs. image vs. carousel), CTA patterns, and auto-generated insights like "Video ads outnumber image ads — competitors are investing in video creative." Every ad also gets computed fields: how many days it's been running, copy length classification, creative type, and more. Run this weekly to spot new creatives and strategy shifts. **Raw Data mode** — Flat, CSV-friendly rows. One record per ad with all extracted fields. Best for bulk export, custom analysis in Google Sheets, or piping into your own dashboard. ### What you get per ad - Ad Library ID, status (active/inactive), start and end dates - Advertiser name, page ID, profile picture - Full ad body text, headline, link caption, link description - Call-to-action button text (Shop Now, Learn More, Sign Up, etc.) - Landing page URL - Image URLs (full resolution) - Video URLs (HD and SD) - Carousel card data (title, body, image, link for each card) - Publisher platforms (Facebook, Instagram, Messenger, Audience Network) - Impression estimates (lower and upper bound) - Spend estimates (lower and upper bound with currency) - **Tracker mode adds:** ad age in days, age bucket, creative type, copy style, CTA flag, landing page flag ### Tracker mode summary report includes - Total ads found, active vs. inactive count - Number of unique advertisers - New ads launched in last 7 days - Creative type breakdown (video / image / carousel / text-only) - Ad age distribution (new / recent / established / long-running) - Top CTAs ranked by frequency - Platform distribution (Facebook vs. Instagram vs. Messenger) - Copy style breakdown (short / medium / long-form) - Advertiser profiles with ad count, creative mix, landing pages, and date ranges - Auto-generated strategic insights ### Use cases **For agencies and media buyers** — Monitor client competitors weekly. See when they launch new creatives, which CTAs they test, whether they're shifting to video, and which landing pages they're driving traffic to. Schedule this to run every Monday morning and review the summary. **For DTC and e-commerce brands** — Spy on what's working in your niche. Find the ads that have been running 60+ days (likely profitable), study their copy and creative approach, and use the insights to inform your own ad strategy. **For affiliate marketers** — Research which offers are being promoted hardest. Filter by keyword (e.g., "teeth whitening", "keto", "solar panels") to see the competitive landscape, identify winning angles, and find landing page inspiration. **For market researchers** — Track advertising trends across industries. Compare creative strategies between brands, monitor ad spend patterns, and build reports on competitive positioning. ### How to run it 1. Enter a brand name, competitor name, or keyword in **Search Keywords** 2. Optionally add specific Facebook Page URLs for targeted tracking 3. Choose your **Output Mode** — Tracker for insights, Raw for bulk data 4. Set the country (defaults to US) 5. Hit Start For weekly competitive monitoring, schedule this actor to run on a recurring basis. Each run captures the current state of your competitors' ad programs so you can track changes over time. ### Input examples **Monitor a specific competitor:** ```json { "searchQueries": ["allbirds"], "outputMode": "tracker", "maxAds": 100, "country": "US" } ```` **Compare multiple competitors in a niche:** ```json { "searchQueries": ["huel", "soylent", "ka'chava"], "outputMode": "tracker", "maxAds": 50, "country": "US" } ``` **Bulk export for spreadsheet analysis:** ```json { "searchQueries": ["running shoes"], "outputMode": "raw", "maxAds": 500, "activeStatus": "all", "country": "US" } ``` **Track a competitor's Facebook page directly:** ```json { "pageUrls": ["https://www.facebook.com/Nike"], "outputMode": "tracker", "maxAds": 200, "country": "US" } ``` ### Sample Tracker output (summary row) ```json { "_type": "tracker_summary", "reportGeneratedAt": "2026-04-05T14:30:00Z", "searchQueries": ["allbirds"], "country": "US", "totalAdsFound": 47, "activeAds": 42, "inactiveAds": 5, "uniqueAdvertisers": 3, "newAdsLast7Days": 8, "creativeTypeBreakdown": { "video": 18, "image": 22, "carousel": 5, "text_only": 2 }, "adAgeBreakdown": { "new (0-7 days)": 8, "recent (8-30 days)": 15, "established (31-90 days)": 12, "long-running (90+ days)": 7, "unknown": 5 }, "insights": [ "8 new ads launched in the last 7 days (17% of total) — this niche is actively being invested in.", "7 ads have been running 60+ days — likely profitable. Advertisers: Allbirds.", "Top advertiser 'Allbirds' has 42 ads — heavy investment in this space." ] } ``` ### Technical details - Uses Playwright to render Meta's Ad Library in a real browser - Intercepts Facebook's GraphQL API responses for structured data extraction - Falls back to DOM extraction if GraphQL intercept returns empty - Residential proxies required (included with Apify subscription) - No Facebook account or API key needed — the Ad Library is public ### Pricing - **Raw mode:** $0.50 per 1,000 ads extracted - **Tracker mode:** $0.50 per 1,000 ads extracted (includes enrichment and summary report at no extra cost) Both modes are billed per result. No start fee. Try it with a small search first to see the output format before scaling up. ### Limitations - Meta's Ad Library shows ads by country, so you need to run separate queries for different markets - Impression and spend data is only available for ads about social issues, elections, or politics - Very new ads (under 24 hours old) may not appear in the library yet - Facebook may occasionally trigger bot detection — residential proxies minimize this # Actor input Schema ## `outputMode` (type: `string`): Choose your output format. 'Competitor Tracker' adds enriched analytics: advertiser profiles, ad age analysis, creative type breakdown, auto-generated insights, and a summary report as the first row — perfect for weekly competitive monitoring. 'Raw Data' gives flat CSV-friendly rows, one record per ad, ideal for bulk export and custom analysis. ## `searchQueries` (type: `array`): Enter brand names, competitor names, or keywords to find their ads. Examples: 'Nike', 'teeth whitening', 'meal kit delivery'. Enter multiple terms to compare competitors side by side. ## `pageUrls` (type: `array`): Track specific competitors by their Facebook page URL. Enter the URL of any Facebook business page to see all their active ads. Example: https://www.facebook.com/Nike ## `country` (type: `string`): Country to search ads in. Use 2-letter ISO code (US, GB, DE, FR, CA, AU, etc.) or full country name. Ads in the Meta Ad Library are country-specific. ## `maxAds` (type: `integer`): How many ads to collect per search query or page. For weekly monitoring, 50-100 is usually enough to spot new creatives. For deep competitive research, go up to 500+. Higher values take longer. ## `activeStatus` (type: `string`): Filter by ad status. 'Active' shows currently running ads (best for competitive monitoring). 'All' includes stopped ads too — useful for seeing what competitors have tested and killed. ## `adType` (type: `string`): Type of ads to search. 'All' covers standard commercial ads plus political/social issue ads. ## `mediaType` (type: `string`): Filter by creative format. Use 'Videos only' to research video ad strategies, or 'Images only' to focus on static creatives and display ads. ## `proxyConfiguration` (type: `object`): Residential proxies are required — Meta's Ad Library blocks datacenter IPs. The default Apify residential proxy works reliably. ## Actor input object example ```json { "outputMode": "tracker", "searchQueries": [ "nike" ], "pageUrls": [], "country": "US", "maxAds": 100, "activeStatus": "active", "adType": "all", "mediaType": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # 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 = { "outputMode": "tracker", "searchQueries": [ "nike" ], "pageUrls": [], "country": "US", "maxAds": 100, "activeStatus": "active", "adType": "all", "mediaType": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("nexgendata/facebook-ads-library-scraper").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 = { "outputMode": "tracker", "searchQueries": ["nike"], "pageUrls": [], "country": "US", "maxAds": 100, "activeStatus": "active", "adType": "all", "mediaType": "all", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("nexgendata/facebook-ads-library-scraper").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 '{ "outputMode": "tracker", "searchQueries": [ "nike" ], "pageUrls": [], "country": "US", "maxAds": 100, "activeStatus": "active", "adType": "all", "mediaType": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call nexgendata/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=nexgendata/facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "📢 Facebook Ads Scraper — Competitor Ad Tracker", "description": "Scrape Meta's Ad Library for active Facebook and Instagram ads. Track competitor ad creatives, spend estimates, targeting, and campaign duration. Essential for ad intelligence and competitive research.", "version": "0.0", "x-build-id": "mNQ7hR7IPwU4KRKCO" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nexgendata~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nexgendata-facebook-ads-library-scraper", "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/nexgendata~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-nexgendata-facebook-ads-library-scraper", "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/nexgendata~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-nexgendata-facebook-ads-library-scraper", "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": { "outputMode": { "title": "Output Mode", "enum": [ "tracker", "raw" ], "type": "string", "description": "Choose your output format. 'Competitor Tracker' adds enriched analytics: advertiser profiles, ad age analysis, creative type breakdown, auto-generated insights, and a summary report as the first row — perfect for weekly competitive monitoring. 'Raw Data' gives flat CSV-friendly rows, one record per ad, ideal for bulk export and custom analysis.", "default": "tracker" }, "searchQueries": { "title": "Search Keywords or Brand Names", "type": "array", "description": "Enter brand names, competitor names, or keywords to find their ads. Examples: 'Nike', 'teeth whitening', 'meal kit delivery'. Enter multiple terms to compare competitors side by side.", "items": { "type": "string" } }, "pageUrls": { "title": "Facebook Page URLs (optional)", "type": "array", "description": "Track specific competitors by their Facebook page URL. Enter the URL of any Facebook business page to see all their active ads. Example: https://www.facebook.com/Nike", "items": { "type": "string" } }, "country": { "title": "Target Country", "type": "string", "description": "Country to search ads in. Use 2-letter ISO code (US, GB, DE, FR, CA, AU, etc.) or full country name. Ads in the Meta Ad Library are country-specific.", "default": "US" }, "maxAds": { "title": "Maximum Ads to Extract", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many ads to collect per search query or page. For weekly monitoring, 50-100 is usually enough to spot new creatives. For deep competitive research, go up to 500+. Higher values take longer.", "default": 100 }, "activeStatus": { "title": "Ad Status Filter", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by ad status. 'Active' shows currently running ads (best for competitive monitoring). 'All' includes stopped ads too — useful for seeing what competitors have tested and killed.", "default": "active" }, "adType": { "title": "Ad Type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Type of ads to search. 'All' covers standard commercial ads plus political/social issue ads.", "default": "all" }, "mediaType": { "title": "Media Type Filter", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Filter by creative format. Use 'Videos only' to research video ad strategies, or 'Images only' to focus on static creatives and display ads.", "default": "all" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Residential proxies are required — Meta's Ad Library blocks datacenter IPs. The default Apify residential proxy works reliably.", "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 } } } } } } } } } } ```