# Facebook Ads Library Scraper - Spy on Competitor Ads (`convertfleetdotonline/facebook-ads-library-scraper`) Actor Scrape the Facebook Ads Library by keyword, country & ad type. Get advertiser, ad copy, creative images, status, start date & library ID. No login. Spy on competitor ads. - **URL**: https://apify.com/convertfleetdotonline/facebook-ads-library-scraper.md - **Developed by:** [Hasnain Nisar](https://apify.com/convertfleetdotonline) (community) - **Categories:** Marketing, Social media - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $0.49 / 1,000 ad scrapeds 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 The **Facebook Ads Library Scraper** pulls competitor ads at scale from the public [Facebook Ad Library](https://www.facebook.com/ads/library) — ad creative copy, images, status (active/inactive), start dates, target location, and Meta's unique Library ID. Search by keyword, brand, or advertiser and get clean JSON with no API key, no login, and no rate-limit headaches. It's the go-to tool for **competitor ad research**, building a **swipe file of winning creative**, and **market intelligence** across any niche. ### What does the Facebook Ads Library Scraper Actor do? The Facebook Ads Library Scraper is a no-code tool that collects publicly available ads from Facebook's Ad Library transparency platform and exports them as JSON, CSV, or Excel. Pass a keyword, brand name, or advertiser and the actor returns a structured list of ads — the exact creative and metadata Meta serves in its own UI. Filter by country, ad type, and status to narrow results to your jurisdiction or category. - **Spy on competitor Facebook ads** — see every ad a rival brand is currently running - **Extract ad creative copy** — the actual ad body text Meta publishes - **Get ad creative images** — the first creative image URL per ad - **Filter by ad status** — `active`, `inactive`, or `ALL` - **Filter by country** — any ISO 2-letter code or `ALL` worldwide - **Filter by ad type** — all ads, or political/issue, housing, employment, and credit categories - **Capture impressions range and start dates** — when Meta publishes them - **Bulk-friendly** — up to 200 ads per query, scriptable into batch runs ### What data can I extract from the Facebook Ads Library? Each ad record contains the following fields: | Field | Description | |-------|-------------| | `advertiser` | Advertiser name | | `page_name` | Facebook Page running the ad | | `ad_text` | Ad creative copy (body text) | | `ad_creative_body` | Ad creative body (full text) | | `image_url` | First creative image URL | | `ad_creative_image_url` | Creative image URL | | `platform` | Platform the ad runs on (e.g. Facebook) | | `status` | Ad status (`active` / `inactive`) | | `ad_delivery_status` | Delivery status reported by Meta | | `start_date` | Date the ad first ran | | `impressions` | Impressions range (`lower_bound` / `upper_bound`) when published | | `target_location` | Geographic targeting | | `library_id` | Facebook's unique Ad Library ID | ### How to scrape the Facebook Ads Library (step-by-step) 1. Open the Facebook Ads Library Scraper on Apify and click **Try for free**. 2. Enter a **query** — a keyword, brand, or advertiser name (e.g. "marketing software"). 3. Set the **country** (ISO 2-letter code or `ALL`) and **ad type** filter. 4. Choose a **status**: `active`, `inactive`, or `ALL`, and set **Max ads** (1–200). 5. Click **Start** and let the actor harvest ads from the public Ad Library. 6. Export results to **JSON, CSV, Excel, or Google Sheets**, or pull them via the Apify API. 7. To cover several keywords, run the actor once per keyword and merge the datasets. ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `query` | string | — | Keyword or advertiser name to search the Ads Library (e.g. "crypto wallet", "Nike"). **Required.** | | `country` | string | `ALL` | Two-letter ISO country code (e.g. `US`, `DE`, `GB`) or `ALL` for worldwide. | | `adType` | string (enum) | `ALL` | `ALL`, `POLITICAL_AND_ISSUE_ADS`, `HOUSING_ADS`, `EMPLOYMENT_ADS`, or `CREDIT_ADS`. | | `status` | string (enum) | `active` | Filter by `active`, `inactive`, or `ALL`. | | `maxResults` | integer | `20` | Maximum ads to return (1–200). | | `proxyConfiguration` | object | Apify proxy | Routes through Apify Proxy; US residential recommended for English-locale content. | Example input: ```json { "query": "marketing software", "country": "US", "adType": "ALL", "status": "active", "maxResults": 50 } ```` ### Output example ```json { "advertiser": "Acme Corp", "page_name": "Acme Corp", "ad_text": "Try our new productivity tool — 50% off the first month!", "ad_creative_body": "Try our new productivity tool — 50% off the first month!", "image_url": "https://scontent.xx.fbcdn.net/...", "ad_creative_image_url": "https://scontent.xx.fbcdn.net/...", "platform": "Facebook", "status": "active", "ad_delivery_status": "active", "start_date": "2024-08-15", "impressions": { "lower_bound": 50000, "upper_bound": 100000 }, "target_location": "United States", "library_id": "1234567890123456" } ``` ### Use cases - **Competitor ad research** — enumerate every ad your top competitors are currently running. - **Ad copy inspiration** — surface high-frequency messaging in your category for new creative. - **Creative swipe file** — build a library of winning ad creative and images. - **Compliance and due diligence** — verify a brand's political or issue ad activity. - **Market intelligence** — measure share-of-voice and ad volume across a category. - **PR and journalism** — investigate political and issue ad spend and targeting. ### Pricing The Facebook Ads Library Scraper runs on Apify's usage-based pricing — you pay for the compute units and proxy traffic each run uses, with no separate subscription. A 20-ad scrape completes in 15–25 seconds and a 200-ad scrape in 30–50 seconds (memory ~1 GB for Chromium). See the actor's **Pricing** tab for current rates and free-tier credits. ### Why this Facebook Ads Library Scraper? Meta's official Ad Library API is limited and gated, and DOM-only scrapers break whenever the page markup changes. This actor uses both approaches: it intercepts the GraphQL responses that power Facebook's own Ad Library UI for the cleanest, most accurate metadata, and falls back to a DOM-based "Library ID"-anchored scraper when GraphQL isn't available. Combined with country, ad-type, and status filters, that makes it a reliable way to monitor competitor campaigns without tokens or approvals. ### FAQ #### Is it legal to scrape the Facebook Ads Library? The Facebook Ads Library is a transparency tool that Meta itself publishes for journalists, researchers, advertisers, and the public, so the data is public by design. Scraping public data is broadly permitted, but you remain responsible for complying with Meta's Terms of Service and applicable laws such as GDPR and CCPA. #### Do I need a Facebook account or Ad Library API key? No. The actor works on the public Ad Library pages with no login and no Meta Ad Library API token. #### How much does it cost to scrape Facebook ads? It runs on Apify's pay-as-you-go pricing, so cost scales with how many ads you scrape and the proxy traffic used. Small runs are inexpensive and the free tier covers testing. See the Pricing tab for exact figures. #### How many ads can I scrape and how fast? Up to 200 ads per query. A 20-ad scrape finishes in ~15–25 seconds and a 200-ad scrape in ~30–50 seconds. #### Can I get spend and impression numbers? Meta only publishes impressions and spend for political and issue ads. For commercial ads, those fields are typically empty. #### Why do some queries return 0 ads? Either no ads match, the country filter is too narrow, or Meta is rate-limiting. Try a broader query, switch country to `ALL`, or re-run. #### Can I export the ads to CSV, Excel, JSON, or Google Sheets? Yes. Every dataset can be exported to JSON, CSV, Excel, XML, or Google Sheets, or fetched via the Apify API. #### How do I scrape ads for multiple keywords? Run the actor once per keyword and merge the datasets, or trigger it through the Apify API in a loop for fully automated batch runs. ### Related actors - [Facebook Page Scraper](https://apify.com/hasnainnisar67/facebook-page-scraper) — page contact info, followers, and about - [TikTok Scraper](https://apify.com/hasnainnisar67/tiktok-scraper) — TikTok profiles, hashtags, and search - [Twitter / X Scraper](https://apify.com/hasnainnisar67/twitter-scraper) — bulk tweet and profile scraping - [Instagram Downloader](https://apify.com/hasnainnisar67/instagram-downloader) — download Instagram media - [LinkedIn Profile Scraper](https://apify.com/hasnainnisar67/linkedin-profile-scraper) — bulk LinkedIn profile data ### Support Need an extra field, filter, or output format? Open an issue on the actor's **Issues** tab. Custom ad-intelligence solutions and integrations are available on request. # Actor input Schema ## `query` (type: `string`): Keyword to search for in the Facebook Ads Library (e.g. 'crypto wallet', 'Nike', 'apartment Berlin'). ## `country` (type: `string`): Two-letter ISO country code (e.g. 'US', 'DE', 'GB') or 'ALL' for worldwide. ## `adType` (type: `string`): Ad type filter. Use 'ALL', 'POLITICAL\_AND\_ISSUE\_ADS', 'HOUSING\_ADS', 'EMPLOYMENT\_ADS', 'CREDIT\_ADS'. ## `status` (type: `string`): Filter by ad status: active (currently running), inactive (no longer running), or ALL. ## `maxResults` (type: `integer`): Maximum number of ads to return (1-200). ## `proxyConfiguration` (type: `object`): Routes Playwright through Apify Proxy. Use US residential for accurate English-locale page content. ## Actor input object example ```json { "query": "marketing software", "country": "ALL", "adType": "ALL", "status": "active", "maxResults": 20, "proxyConfiguration": { "useApifyProxy": true } } ``` # 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 = { "query": "marketing software", "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("convertfleetdotonline/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 = { "query": "marketing software", "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("convertfleetdotonline/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 '{ "query": "marketing software", "proxyConfiguration": { "useApifyProxy": true } }' | apify call convertfleetdotonline/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=convertfleetdotonline/facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper - Spy on Competitor Ads", "description": "Scrape the Facebook Ads Library by keyword, country & ad type. Get advertiser, ad copy, creative images, status, start date & library ID. No login. Spy on competitor ads.", "version": "0.1", "x-build-id": "sOmmy7u8TsWsRUaSr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/convertfleetdotonline~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-convertfleetdotonline-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/convertfleetdotonline~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-convertfleetdotonline-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/convertfleetdotonline~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-convertfleetdotonline-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", "required": [ "query" ], "properties": { "query": { "title": "Search keyword or advertiser", "type": "string", "description": "Keyword to search for in the Facebook Ads Library (e.g. 'crypto wallet', 'Nike', 'apartment Berlin')." }, "country": { "title": "Country code", "type": "string", "description": "Two-letter ISO country code (e.g. 'US', 'DE', 'GB') or 'ALL' for worldwide.", "default": "ALL" }, "adType": { "title": "Ad type", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "Ad type filter. Use 'ALL', 'POLITICAL_AND_ISSUE_ADS', 'HOUSING_ADS', 'EMPLOYMENT_ADS', 'CREDIT_ADS'.", "default": "ALL" }, "status": { "title": "Ad status", "enum": [ "active", "inactive", "ALL" ], "type": "string", "description": "Filter by ad status: active (currently running), inactive (no longer running), or ALL.", "default": "active" }, "maxResults": { "title": "Max ads to return", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of ads to return (1-200).", "default": 20 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Routes Playwright through Apify Proxy. Use US residential for accurate English-locale page content.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```