# Facebook Ads Library Scraper v2 (`prodiger/facebook-ads-library-scraper-v2`) Actor Search Meta's Ad Library by keyword, page handle, page URL, or full Ad Library URL. Pay-per-result. - **URL**: https://apify.com/prodiger/facebook-ads-library-scraper-v2.md - **Developed by:** [Arnas](https://apify.com/prodiger) (community) - **Categories:** Social media, Lead generation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $0.75 / 1,000 ads 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 Search Meta's Ad Library and pull every matching ad. Pass a keyword, a Facebook page handle, a page URL, or a full Ad Library URL — they all work. ### Quick start The minimum viable input is a single field: ```json { "query": ["crochet"] } ```` Or mix searches in a single run: ```json { "query": ["crochet", "@ZapierApp", "https://www.facebook.com/Nike"], "country": "US", "activeStatus": "active", "maxAds": 500 } ``` ### Input | Field | Type | Default | What it does | | ----------------- | --------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `query` | `string[]` (required) | — | Keywords (`crochet`), page handles (`@ZapierApp`), page URLs, or full Ad Library URLs. Mix freely. | | `country` | `string` | `ALL` | Two-letter ISO country code (`US`, `GB`, `DE`, …) or `ALL`. | | `activeStatus` | `enum` | `active` | `all` · `active` · `inactive`. | | `adType` | `enum` | `all` | `all` · `political_and_issue_ads`. | | `mediaType` | `enum` | `all` | `all` · `image` · `video` · `meme` · `image_and_meme` · `none`. | | `period` | `enum` | `all` | `all` · `last24h` · `last7d` · `last14d` · `last30d`. | | `sortBy` | `enum` | `impressions_desc` | `impressions_desc` · `most_recent`. | | `maxAds` | `integer` | `100` | Total cap across all searches. Empty for no cap. | | `maxAdsPerQuery` | `integer` | unlimited | Cap per item in `query`. | | `scrapeAdDetails` | `boolean` | `false` | Fetch extra ad details (e.g. EU reach). Slower and more expensive. | | `runTag` | `string` | — | Stamped onto every output row's `runTag` field. | | `proxy` | `proxy` | Apify Proxy | Override proxy configuration. | #### Legacy fields (still accepted) For drop-in compatibility with the original `curious_coder/facebook-ads-library-scraper` input, these older field names are also accepted: - `urls` (array of URL objects) → folded into `query` - `count` → `maxAds` - `limitPerSource` → `maxAdsPerQuery` - `scrapePageAds.countryCode` → `country` - `scrapePageAds.activeStatus` → `activeStatus` - `scrapePageAds.period` → `period` - `scrapePageAds.sortBy` → `sortBy` ### Output Each ad is pushed to the run's default dataset with the upstream Meta field names preserved (`ad_archive_id`, `page_name`, `is_active`, `start_date_formatted`, `publisher_platform`, `snapshot`, `spend`, `reach_estimate`, `advertiser`, `insights`, `aaa_info`, …) plus three convenience fields: - `ad_library_url` — direct link to the ad - `position` — index within the run (1-based) - `query` — which input item produced the row - `runTag` — copy of the input `runTag` ### Pricing Pay per event: - Event key: `apify-default-dataset-item` - Event title: `ad` - Event description: `Single ad in the default dataset.` - Event price: `$0.00075` Displays as **$0.75 / 1,000 ads**. # Actor input Schema ## `query` (type: `array`): One or more searches. Each item can be: - A keyword, e.g. `crochet`, `running shoes` - A Facebook page handle, e.g. `@ZapierApp` or `ZapierApp` - A Facebook page URL, e.g. `https://www.facebook.com/ZapierApp` - A full Facebook Ad Library URL (for full control over filters) ## `country` (type: `string`): Two-letter ISO country code (e.g. `US`, `GB`, `DE`, `IN`). Use `ALL` to search every country. ## `activeStatus` (type: `string`): Filter by whether the ad is currently running. ## `adType` (type: `string`): Restrict to all ads or only political & social-issue ads. ## `mediaType` (type: `string`): Filter by the type of creative. ## `period` (type: `string`): Only when searching ads run by a specific page. ## `sortBy` (type: `string`): Sort ads by impressions (highest first) or by most recent. ## `maxAds` (type: `integer`): Stop the run after this many ads have been collected across all searches. Leave empty for no total cap. ## `maxAdsPerQuery` (type: `integer`): Cap ads collected per item in `query`. Leave empty for no per-search cap. ## `scrapeAdDetails` (type: `boolean`): Fetch extra details (e.g. EU reach) for each ad. Slower and more expensive. ## `runTag` (type: `string`): Optional label written into every output row's `runTag` field — handy when joining datasets later. ## `proxy` (type: `object`): Optional proxy configuration. Defaults to Apify Proxy if omitted. ## Actor input object example ```json { "query": [ "crochet" ], "country": "ALL", "activeStatus": "active", "adType": "all", "mediaType": "all", "period": "all", "sortBy": "impressions_desc", "maxAds": 100, "scrapeAdDetails": false, "proxy": { "useApifyProxy": true } } ``` # Actor output Schema ## `dataset` (type: `string`): Scraped Facebook / Meta Ad Library ads. # 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": [ "crochet" ], "country": "ALL", "activeStatus": "active", "adType": "all", "mediaType": "all", "period": "all", "sortBy": "impressions_desc", "maxAds": 100, "proxy": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("prodiger/facebook-ads-library-scraper-v2").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": ["crochet"], "country": "ALL", "activeStatus": "active", "adType": "all", "mediaType": "all", "period": "all", "sortBy": "impressions_desc", "maxAds": 100, "proxy": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("prodiger/facebook-ads-library-scraper-v2").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": [ "crochet" ], "country": "ALL", "activeStatus": "active", "adType": "all", "mediaType": "all", "period": "all", "sortBy": "impressions_desc", "maxAds": 100, "proxy": { "useApifyProxy": true } }' | apify call prodiger/facebook-ads-library-scraper-v2 --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=prodiger/facebook-ads-library-scraper-v2", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper v2", "description": "Search Meta's Ad Library by keyword, page handle, page URL, or full Ad Library URL. Pay-per-result.", "version": "0.1", "x-build-id": "5Z1fZIihiAfuVLuDL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/prodiger~facebook-ads-library-scraper-v2/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-prodiger-facebook-ads-library-scraper-v2", "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/prodiger~facebook-ads-library-scraper-v2/runs": { "post": { "operationId": "runs-sync-prodiger-facebook-ads-library-scraper-v2", "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/prodiger~facebook-ads-library-scraper-v2/run-sync": { "post": { "operationId": "run-sync-prodiger-facebook-ads-library-scraper-v2", "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": "🔎 What to search for", "minItems": 1, "uniqueItems": true, "type": "array", "description": "One or more searches. Each item can be:\n- A keyword, e.g. `crochet`, `running shoes`\n- A Facebook page handle, e.g. `@ZapierApp` or `ZapierApp`\n- A Facebook page URL, e.g. `https://www.facebook.com/ZapierApp`\n- A full Facebook Ad Library URL (for full control over filters)", "items": { "type": "string" } }, "country": { "title": "🌍 Country", "pattern": "^([A-Z]{2}|ALL|all)$", "type": "string", "description": "Two-letter ISO country code (e.g. `US`, `GB`, `DE`, `IN`). Use `ALL` to search every country.", "default": "ALL" }, "activeStatus": { "title": "Status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter by whether the ad is currently running.", "default": "active" }, "adType": { "title": "Ad type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Restrict to all ads or only political & social-issue ads.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Filter by the type of creative.", "default": "all" }, "period": { "title": "Date range", "enum": [ "all", "last24h", "last7d", "last14d", "last30d" ], "type": "string", "description": "Only when searching ads run by a specific page.", "default": "all" }, "sortBy": { "title": "Sort by", "enum": [ "impressions_desc", "most_recent" ], "type": "string", "description": "Sort ads by impressions (highest first) or by most recent.", "default": "impressions_desc" }, "maxAds": { "title": "Max ads (total)", "minimum": 1, "type": "integer", "description": "Stop the run after this many ads have been collected across all searches. Leave empty for no total cap." }, "maxAdsPerQuery": { "title": "Max ads per search", "minimum": 1, "type": "integer", "description": "Cap ads collected per item in `query`. Leave empty for no per-search cap." }, "scrapeAdDetails": { "title": "Scrape ad details", "type": "boolean", "description": "Fetch extra details (e.g. EU reach) for each ad. Slower and more expensive.", "default": false }, "runTag": { "title": "Run tag", "type": "string", "description": "Optional label written into every output row's `runTag` field — handy when joining datasets later." }, "proxy": { "title": "Proxy", "type": "object", "description": "Optional proxy configuration. Defaults to Apify Proxy if omitted.", "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 } } } } } } } } } } ```