# Facebook Ads Scraper (`leadsbrary/facebook-ads-scraper`) Actor Spy on any brand's ads across Facebook, Instagram, Threads & Messenger. Pull ad creatives, copy, targeting, publishers, impressions, and timestamps directly from Meta Ad Library. Schedule runs, export to CSV/JSON, and plug into AI workflows via API. - **URL**: https://apify.com/leadsbrary/facebook-ads-scraper.md - **Developed by:** [Alexandre Manguis](https://apify.com/leadsbrary) (community) - **Categories:** Social media, SEO tools, Integrations - **Stats:** 6 total users, 4 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.30 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Scraper Scrape the [Meta (Facebook/Instagram) Ads Library](https://www.facebook.com/ads/library/) to extract ads from any advertiser or keyword search — faster and richer than other scrapers. Just paste a **Facebook page URL** or a **Meta Ad Library search URL** and run. No login required. ### ✨ What you get - **Ad status** — `isActive` boolean: `true` for running ads, `false` for stopped - **Ad format** — `snapshot.displayFormat`: `DPA` (Dynamic Product), `DCO` (Dynamic Creative), or `STANDARD` - **Ad title** — `snapshot.title`: the main creative headline or body text - **Publisher platforms** — `FACEBOOK`, `INSTAGRAM`, `AUDIENCE_NETWORK`, `MESSENGER`, `THREADS` - **Delivery dates** — `startDateFormatted`, `endDateFormatted` in ISO 8601 - **Advertiser name** — `pageInfo.page.name` - **Ad text** — full creative body text - **Ad Library link** — direct link to the ad in Meta's library - **Bonus fields** (vs. competitors) — page category, likes, verification, Instagram username, CTA domain, headline, description, snapshot URL ### 📦 Sample output ```json [ { "pageInfo.page.name": "Nike", "snapshot.title": "Just Do It. Shop the latest collection.", "snapshot.displayFormat": "DCO", "isActive": true, "spend": null, "reachEstimate": null, "publisherPlatform": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"], "startDateFormatted": "2026-02-27T08:00:00.000Z", "endDateFormatted": "2026-04-11T07:00:00.000Z", "adArchiveID": "3948271054812", "pageID": "15087023444", "pageURL": "https://www.facebook.com/15087023444", "pageCategory": "Sportswear store", "pageLikes": 34800000, "pageVerified": true, "pageInstagramUser": "nike", "pageInstagramFollowers": 302000000, "pageCountry": "US", "adText": "Just Do It. Shop the latest collection.", "adCreativeBodies": ["Just Do It. Shop the latest collection.", "New arrivals — limited time only."], "languages": ["en"], "adLibraryURL": "https://www.facebook.com/ads/library/?id=3948271054812" }, { "pageInfo.page.name": "SHEIN", "snapshot.title": "{{product.name}}", "snapshot.displayFormat": "DPA", "isActive": false, "spend": null, "reachEstimate": null, "publisherPlatform": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK"], "startDateFormatted": "2025-02-04T08:00:00.000Z", "endDateFormatted": "2025-06-25T07:00:00.000Z", "adArchiveID": "7261039485012", "pageID": "380039845369159", "pageURL": "https://www.facebook.com/380039845369159", "adText": "{{product.name}}", "adCreativeBodies": ["{{product.name}}"], "languages": null, "adLibraryURL": "https://www.facebook.com/ads/library/?id=7261039485012" } ] ```` ### 🚀 Usage #### Input | Field | Type | Default | Description | |---|---|---|---| | `startUrls` | array | — | **Required.** Facebook page URLs or Meta Ad Library search URLs | | `resultsLimit` | number | 10 | Max ads to return per URL | | `activeStatus` | string | `""` | Filter: `ACTIVE`, `INACTIVE`, or `ALL` (blank = use URL's filter) | | `includeAboutPage` | boolean | false | Add page category, likes, Instagram info | | `isDetailsPerAd` | boolean | false | Add CTA domain, headline, description, snapshot URL | | `onlyTotal` | boolean | false | Return only the total ad count (no ad data) | | `countryFallback` | string | `ALL` | Country code when not set in URL | #### Supported URL formats **Facebook page URL** — extract all ads from a specific advertiser: ``` https://www.facebook.com/nike https://www.facebook.com/SHEINOFFICIAL https://www.facebook.com/15087023444 ``` **Meta Ad Library search URL** — copy-paste from [facebook.com/ads/library](https://www.facebook.com/ads/library/) with any filters applied: ``` https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&media_type=video https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&search_type=page&view_all_page_id=15087023444&publisher_platforms[0]=instagram ``` You can mix both types in the same run. #### Example input (compatible with `apify/facebook-ads-scraper`) ```json { "startUrls": [ { "url": "https://www.facebook.com/SHEINOFFICIAL" }, { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&media_type=image&publisher_platforms[0]=instagram&search_type=page&view_all_page_id=15087023444" } ], "resultsLimit": 20, "activeStatus": "ACTIVE", "includeAboutPage": false, "isDetailsPerAd": false } ``` ### 💡 Tips - **Keyword search**: paste a full Ad Library URL with `q=your+keyword` to search ads by keyword across all advertisers. - **Page ads**: use a Facebook page URL (or `view_all_page_id` in the URL) to get all ads from a specific brand. - **Smart page discovery**: when a keyword search returns fewer results than expected (e.g. the brand name doesn't appear in ad body text), the scraper automatically discovers the advertiser's pages by name and queries them directly. - **DPA detection**: ads with `snapshot.displayFormat = "DPA"` use dynamic product catalogs — the title shows `{{product.name}}` which is normal (Meta doesn't expose the actual product names). - Use `onlyTotal: true` to count ads before committing to a full scrape. ### 💰 Pricing Charged per result: **$0.0015 per ad** ($1.50 per 1,000 ads) plus a flat **$0.005 per run**. This is **2–4× cheaper** than comparable Facebook ads scrapers on the Apify marketplace. > Spend data and audience estimates are `null` for standard commercial ads — Meta only provides these for Special Ad Categories (political, housing, employment). ### ⚠️ Limitations - Uses the **public Meta Ads Library API** — no login, no private data. - `spend` and `reachEstimate` are always `null` for standard ads (Meta API restriction). - Health/pharmaceutical advertisers may return 0 results due to Meta platform restrictions on API access for those categories. *** ### 🔍 Keywords Facebook ads scraper, Meta ads library scraper, Facebook ad library, Instagram ads scraper, Facebook advertising data, scrape Facebook ads, ad spy tool, competitor ad research, Facebook ads intelligence, social media ads scraper, Facebook ads dataset, Meta ads extractor, paid ads research, Facebook ads monitoring, Facebook page ads extractor, brand ads scraper, Facebook ads export JSON CSV, ad creative scraper, Facebook ads active status, publisher platform ads, DPA scraper, dynamic product ads, DCO ads extractor, Facebook ads automation, Apify Facebook, ecommerce competitor ads, dropshipping ad research, Facebook ads analytics, multi-country Facebook ads, Instagram ads data, Facebook ads by page, Messenger ads, Audience Network ads, Threads ads, Facebook ads start date end date, ad delivery dates, Facebook advertiser category, page likes scraper, verified page ads, Instagram username from Facebook ads, CTA domain scraper, Facebook ads headline, ad snapshot URL, Facebook ads count, ad library bulk download # Actor input Schema ## `startUrls` (type: `array`): List of URLs to scrape. Supports: - **Facebook page URLs** (e.g. `https://www.facebook.com/nike` or `https://www.facebook.com/15087023444`) - **Meta Ad Library search URLs** (copy-paste directly from the Ad Library — all filters are preserved) Each item can be a plain string or an object with a `url` key. ## `resultsLimit` (type: `integer`): Maximum number of ads to return per URL. ## `activeStatus` (type: `string`): Filter by ad delivery status. Leave blank (or `ALL`) to return both active and inactive ads. ## `includeAboutPage` (type: `boolean`): Enrich each ad with the advertiser's Facebook page data: category, likes, verification status, Instagram username & followers, country. ## `isDetailsPerAd` (type: `boolean`): Include full creative details: CTA domain, headline, description, and ad snapshot URL. ## `onlyTotal` (type: `boolean`): Return only the total count of matching ads, without fetching ad data. ## `countryFallback` (type: `string`): 2-letter country code to use when no country is detected in the URL (e.g. `US`, `FR`, `GB`). Use `ALL` to search globally. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&content_languages[0]=en&country=ALL&is_targeted_country=false&media_type=image&publisher_platforms[0]=instagram&publisher_platforms[1]=facebook&search_type=page&view_all_page_id=15087023444" }, { "url": "https://www.facebook.com/SHEINOFFICIAL" } ], "resultsLimit": 10, "activeStatus": "", "includeAboutPage": true, "isDetailsPerAd": true, "onlyTotal": false, "countryFallback": "ALL" } ``` # Actor output Schema ## `results` (type: `string`): Dataset containing all scraped Meta Ads Library records (ad text, page info, platforms, dates, CTA 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 = { "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&content_languages[0]=en&country=ALL&is_targeted_country=false&media_type=image&publisher_platforms[0]=instagram&publisher_platforms[1]=facebook&search_type=page&view_all_page_id=15087023444" }, { "url": "https://www.facebook.com/SHEINOFFICIAL" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("leadsbrary/facebook-ads-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 = { "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&content_languages[0]=en&country=ALL&is_targeted_country=false&media_type=image&publisher_platforms[0]=instagram&publisher_platforms[1]=facebook&search_type=page&view_all_page_id=15087023444" }, { "url": "https://www.facebook.com/SHEINOFFICIAL" }, ] } # Run the Actor and wait for it to finish run = client.actor("leadsbrary/facebook-ads-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 '{ "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&content_languages[0]=en&country=ALL&is_targeted_country=false&media_type=image&publisher_platforms[0]=instagram&publisher_platforms[1]=facebook&search_type=page&view_all_page_id=15087023444" }, { "url": "https://www.facebook.com/SHEINOFFICIAL" } ] }' | apify call leadsbrary/facebook-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=leadsbrary/facebook-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Scraper", "description": "Spy on any brand's ads across Facebook, Instagram, Threads & Messenger. Pull ad creatives, copy, targeting, publishers, impressions, and timestamps directly from Meta Ad Library. Schedule runs, export to CSV/JSON, and plug into AI workflows via API.", "version": "1.0", "x-build-id": "1mobrGpzN0mHsYcfo" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/leadsbrary~facebook-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-leadsbrary-facebook-ads-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/leadsbrary~facebook-ads-scraper/runs": { "post": { "operationId": "runs-sync-leadsbrary-facebook-ads-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/leadsbrary~facebook-ads-scraper/run-sync": { "post": { "operationId": "run-sync-leadsbrary-facebook-ads-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", "required": [ "startUrls" ], "properties": { "startUrls": { "title": "Start URLs", "type": "array", "description": "List of URLs to scrape. Supports:\n- **Facebook page URLs** (e.g. `https://www.facebook.com/nike` or `https://www.facebook.com/15087023444`)\n- **Meta Ad Library search URLs** (copy-paste directly from the Ad Library — all filters are preserved)\n\nEach item can be a plain string or an object with a `url` key.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "resultsLimit": { "title": "Results limit", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of ads to return per URL.", "default": 10 }, "activeStatus": { "title": "Active status filter", "enum": [ "", "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Filter by ad delivery status. Leave blank (or `ALL`) to return both active and inactive ads.", "default": "" }, "includeAboutPage": { "title": "Include advertiser page info", "type": "boolean", "description": "Enrich each ad with the advertiser's Facebook page data: category, likes, verification status, Instagram username & followers, country.", "default": true }, "isDetailsPerAd": { "title": "Include ad creative details", "type": "boolean", "description": "Include full creative details: CTA domain, headline, description, and ad snapshot URL.", "default": true }, "onlyTotal": { "title": "Only total count", "type": "boolean", "description": "Return only the total count of matching ads, without fetching ad data.", "default": false }, "countryFallback": { "title": "Country (fallback)", "type": "string", "description": "2-letter country code to use when no country is detected in the URL (e.g. `US`, `FR`, `GB`). Use `ALL` to search globally.", "default": "ALL" } } }, "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 } } } } } } } } } } ```