# Facebook & Meta Ad Library Scraper (`refined_numbers/meta-ad-library-scraper`) Actor Scrape ads from the Facebook/Meta Ad Library by keyword, country, ad type, media type, or by Ad Library URL - Plus EU reach and demographics that other scrapers miss. - **URL**: https://apify.com/refined\_numbers/meta-ad-library-scraper.md - **Developed by:** [barry weber](https://apify.com/refined_numbers) (community) - **Categories:** Social media, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 basic 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 ## Meta Ad Library Scraper Scrape the **Facebook / Meta Ad Library** at scale. Search by keyword, country, advertiser Page, single ad, or a pasted Ad Library URL, and get clean, structured ad records — brand, dates, ad copy, call‑to‑actions, images/videos, and publishing platforms. Optionally, turn on **ad details** to also pull each ad's **EU/UK/Brazil reach** and **age / gender / country demographic breakdowns** — transparency data most ad scrapers don't extract. No Facebook login or third‑party API required. ### What you can do with it - **Competitive ad research** — see what brands are running, their creative, copy, and CTAs. - **Audience insight** — for EU/UK/BR ads (and political ads), get who an ad reached, by age, gender, and country. - **Creative inspiration & monitoring** — track active vs. inactive ads, formats (image / video / carousel), and landing pages. - **Advertiser deep‑dives** — pull every ad from a specific Facebook Page. ### Features - 🔎 Search by **keyword**, **country**, **advertiser Page ID**, a **specific ad ID**, or a hand‑built **Ad Library URL**. - 🧱 Rich structured output — brand, dates, body text, **headline / caption / CTA / link**, media URLs, platforms, display format. - 📊 **EU/UK/BR reach + demographics** (opt‑in details mode) — unique transparency data. - 🎯 Filters — ad category, media type, active status, sort order. - 🧹 Clean JSON, one item per ad, ready for export to CSV/Excel/JSON/API. ### Input Provide **one** of `searchTerm`, `startUrl`, `pageId`, or `adId`. A run performs a single Ad Library query. | Field | Description | | --- | --- | | `searchTerm` | A single keyword to search for (Meta allows one keyword per query). | | `country` | Country to search, or `ALL` for global. Default `US`. | | `startUrl` | An Ad Library URL to scrape verbatim (build one in your browser for full filter control). | | `pageId` | Scrape every ad from a specific advertiser by their Facebook Page ID. | | `adId` | Scrape a single ad by its Ad Library ID. | | `adType` | `all`, political & issue, housing, employment, credit, or financial ads. | | `mediaType` | `all`, `image`, `video`, `meme`, or `none`. | | `activeStatus` | `active`, `inactive`, or both. | | `sortBy` | `most_relevant` (by impressions) or `most_recent`. | | `maxResults` | Max ads to collect in the run. | | `scrapeAdDetails` | Off by default. When on, also extracts EU/UK/BR reach + demographics (see below). | The scraper runs on **residential proxy automatically** — no proxy setup needed. #### Example input ```json { "searchTerm": "running shoes", "country": "US", "mediaType": "all", "activeStatus": "active", "maxResults": 50 } ```` ### Output Each scraped ad is one item in the dataset. Example (basic mode): ```json { "ad_archive_id": "933016365009192", "brand_name": "Nike", "brand_id": "15087023444", "is_active": true, "start_date": "2026-05-01T00:00:00+00:00", "end_date": "2026-05-30T00:00:00+00:00", "publisher_platforms": ["FACEBOOK", "INSTAGRAM"], "display_format": "VIDEO", "ad_body_text": "Move with the all-new Pegasus.", "title": "Nike Pegasus 41", "caption": "nike.com", "cta_text": "Shop now", "cta_type": "SHOP_NOW", "link_url": "https://www.nike.com/pegasus", "cta_url": "https://www.nike.com/pegasus", "thumbnail_url": "https://.../preview.jpg", "media": { "type": "video", "video_url": "https://.../ad.mp4", "video_preview_image_url": "https://.../preview.jpg" }, "brand_categories": ["Sportswear"], "brand_like_count": 38000000, "brand_profile_picture_url": "https://.../nike.jpg", "reach": null, "demographic_breakdown": [] } ``` **Always included:** `ad_archive_id`, `brand_name`, `brand_id`, `is_active`, `start_date`, `end_date`, `publisher_platforms`, `display_format`, `ad_body_text`, `title`, `caption`, `cta_text`, `cta_type`, `link_url`, `cta_url`, `link_description`, `thumbnail_url`, `media`, and brand metadata (`brand_categories`, `brand_like_count`, `brand_profile_picture_url`, `brand_profile_uri`). **Added in details mode:** `reach` (EU/UK/BR ad‑delivery reach), `demographic_breakdown` (per‑country age/gender), `location_audience`, `gender_audience`, `age_audience`. ### Two modes **Basic (default)** — fast. Brand, dates, copy, CTAs, media, platforms. Works for any country. **Ad details (`scrapeAdDetails: true`)** — clicks into each ad for **reach + demographics**. This is slower (one click per ad) and capped at **400 ads per run**. > ℹ️ Meta only publishes per‑ad reach and demographics for ads delivered in the **EU/EEA, the UK, and Brazil**, or for **political & issue ads** anywhere. Details runs for any other country are rejected with a clear message — so you never pay for a slow run that returns no demographic data. Use an eligible country (e.g. `DE`, `GB`, `BR`) or set `adType` to political & issue ads. ### How to use 1. Set your **search term** (or Page ID / ad ID / URL) and **country**. 2. Choose filters and **Max results**. 3. (Optional) Enable **Scrape ad details** for reach + demographics (eligible regions only). 4. **Start** the run, then export the dataset as JSON, CSV, or Excel — or pull it via the Apify API. ### Pricing Pay‑per‑result: | Mode | Price | | --- | --- | | Basic ad | **$5 per 1,000 ads** | | Ad with details (reach + demographics) | **$20 per 1,000 ads** | Plus standard Apify platform usage (compute + proxy). Details mode is capped at 400 ads per run. ### Notes - Scrapes only **public** Ad Library data — no login, no private data. - Runs on residential proxy automatically — no proxy configuration required. - A run that legitimately finds no matching ads finishes successfully with an empty dataset and a "No ads found" status; genuine errors fail the run with a clear reason. *** Developer / local setup, project layout, and library usage live in [DEVELOPMENT.md](./DEVELOPMENT.md). # Actor input Schema ## `searchTerm` (type: `string`): A single keyword to search the Ad Library for (Meta only allows one keyword per query). Leave empty if you use a Start URL, Page ID, or Ad ID instead. ## `country` (type: `string`): Which country's ads to search. Meta allows one country per query, or 'ALL' for global. ## `startUrl` (type: `string`): A Facebook Ad Library URL to scrape directly (e.g. a search you built in the browser). Use this for full control over filters. Overrides the search term. ## `pageId` (type: `string`): Scrape every ad from a specific advertiser by their numeric Facebook Page ID. Overrides the search term. ## `adId` (type: `string`): Scrape a single ad by its Ad Library ID (the number shown as 'Library ID' on an ad). Takes priority over all other targets. ## `adType` (type: `string`): Which Ad Library category to search. 'All ads' covers everything; the others are the special transparency categories. ## `mediaType` (type: `string`): Filter ads by their creative media type. ## `activeStatus` (type: `string`): Whether to include currently running ads, stopped ads, or both. ## `sortBy` (type: `string`): Ordering of results in the Ad Library. ## `maxResults` (type: `integer`): Maximum number of ads to collect in this run. In 'Scrape ad details' mode this is automatically capped at 400 (the run clicks into each ad, so larger runs would exceed the time limit). ## `scrapeAdDetails` (type: `boolean`): Click into each ad to extract reach + age/gender/country demographics. Only works for an EU/EEA country, the UK, Brazil, or adType=political\_and\_issue\_ads — Meta does not publish this data for ordinary ads elsewhere, so runs with any other country are rejected. Much slower (one click per ad), capped at 400 ads/run. Leave off for fast scraping of brand, dates, body text, media, and platforms. ## Actor input object example ```json { "searchTerm": "nike", "country": "US", "adType": "all", "mediaType": "all", "activeStatus": "active", "sortBy": "most_relevant", "maxResults": 10, "scrapeAdDetails": false } ``` # Actor output Schema ## `ads` (type: `string`): All scraped ad records (one item per ad) in the run's default dataset — brand, dates, ad copy, CTAs, media, platforms, and (in details mode) EU/UK/BR reach and demographics. # 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 = { "searchTerm": "nike", "maxResults": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("refined_numbers/meta-ad-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 = { "searchTerm": "nike", "maxResults": 10, } # Run the Actor and wait for it to finish run = client.actor("refined_numbers/meta-ad-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 '{ "searchTerm": "nike", "maxResults": 10 }' | apify call refined_numbers/meta-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=refined_numbers/meta-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook & Meta Ad Library Scraper", "description": "Scrape ads from the Facebook/Meta Ad Library by keyword, country, ad type, media type, or by Ad Library URL - Plus EU reach and demographics that other scrapers miss.", "version": "0.1", "x-build-id": "2mHkOfT8TzJ35UphK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/refined_numbers~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-refined_numbers-meta-ad-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/refined_numbers~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-refined_numbers-meta-ad-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/refined_numbers~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-refined_numbers-meta-ad-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": { "searchTerm": { "title": "Search term", "type": "string", "description": "A single keyword to search the Ad Library for (Meta only allows one keyword per query). Leave empty if you use a Start URL, Page ID, or Ad ID instead." }, "country": { "title": "Country", "enum": [ "ALL", "US", "GB", "CA", "AU", "DE", "FR", "ES", "IT", "NL", "SE", "NO", "DK", "FI", "IE", "PT", "PL", "BR", "MX", "AR", "IN", "JP", "KR", "SG", "AE", "SA", "IL", "ZA", "NZ", "BE", "AT", "CH", "TR", "ID", "PH", "TH", "VN", "MY" ], "type": "string", "description": "Which country's ads to search. Meta allows one country per query, or 'ALL' for global.", "default": "US" }, "startUrl": { "title": "Start URL", "type": "string", "description": "A Facebook Ad Library URL to scrape directly (e.g. a search you built in the browser). Use this for full control over filters. Overrides the search term." }, "pageId": { "title": "Facebook Page ID", "type": "string", "description": "Scrape every ad from a specific advertiser by their numeric Facebook Page ID. Overrides the search term." }, "adId": { "title": "Ad Library ID", "type": "string", "description": "Scrape a single ad by its Ad Library ID (the number shown as 'Library ID' on an ad). Takes priority over all other targets." }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads", "financial_products_and_services_ads" ], "type": "string", "description": "Which Ad Library category to search. 'All ads' covers everything; the others are the special transparency categories.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "meme", "video", "none" ], "type": "string", "description": "Filter ads by their creative media type.", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Whether to include currently running ads, stopped ads, or both.", "default": "active" }, "sortBy": { "title": "Sort by", "enum": [ "most_relevant", "most_recent" ], "type": "string", "description": "Ordering of results in the Ad Library.", "default": "most_relevant" }, "maxResults": { "title": "Max results", "minimum": 1, "type": "integer", "description": "Maximum number of ads to collect in this run. In 'Scrape ad details' mode this is automatically capped at 400 (the run clicks into each ad, so larger runs would exceed the time limit).", "default": 10 }, "scrapeAdDetails": { "title": "Scrape ad details (EU reach + demographics)", "type": "boolean", "description": "Click into each ad to extract reach + age/gender/country demographics. Only works for an EU/EEA country, the UK, Brazil, or adType=political_and_issue_ads — Meta does not publish this data for ordinary ads elsewhere, so runs with any other country are rejected. Much slower (one click per ad), capped at 400 ads/run. Leave off for fast scraping of brand, dates, body text, media, and platforms.", "default": false } } }, "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 } } } } } } } } } } ```