# Meta Ad Library Scraper — Facebook + Instagram Ad Spy (`buff_pineapple/meta-ad-library-scraper`) Actor Scrape Meta (Facebook + Instagram) Ad Library globally. No login. Filter by keyword, Page ID, country, ad type, media, platform, language. Returns creative URLs (video HD/SD + images), landing pages, captions, CTA, spend & impressions for political/EU ads. - **URL**: https://apify.com/buff\_pineapple/meta-ad-library-scraper.md - **Developed by:** [yossef Nagy](https://apify.com/buff_pineapple) (community) - **Categories:** Marketing, Social media, E-commerce - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 — Facebook + Instagram Ad Spy Scrape Meta's public **Ad Library** at `facebook.com/ads/library/` — every active and inactive ad running on Facebook, Instagram, Messenger, and Audience Network. No login. No browser. Pure HTTP. Global coverage. ### What it returns (per ad) Every claim in this list has been verified end-to-end against the live Ad Library: - **Ad ID** (`ad_archive_id`) and a one-click link to view it on facebook.com/ads/library - **Active / inactive** flag - **Advertiser Page**: `page_id`, `page_name`, profile URL + picture, page like count, page categories - **Branded-content advertiser** (when applicable) — surfaces the *true* advertiser behind influencer posts - **Creative**: - HD + SD video URLs (`video_hd_url`, `video_sd_url`) - Watermarked variants (`watermarked_video_hd_url`, `watermarked_video_sd_url`) - Video preview thumbnail - Full image set (original + resized) - Carousel cards (when the ad is a carousel) - Extra creatives (gallery / multi-image ads) - **Copy**: `body_text` (caption), `title`, `caption` (display URL), `link_description` - **Call-to-action**: `cta_text`, `cta_type` (`SHOP_NOW`, `INSTALL_NOW`, `LEARN_MORE`, …) - **Landing page**: `link_url` (the URL the ad sends to — perfect for chaining into store-fingerprinting actors) - **Format**: `display_format` (`VIDEO`, `IMAGE`, `DCO`, `DPA`, etc.) - **Regulated-disclosure data** (for political/issue ads + EU ads): - `spend` (range string, e.g. `"$9K-$10K USD"`) - `currency` - `impressions_text` (range, e.g. `">1M"`) - `reach_estimate` - `byline` (the disclaimer "Paid for by …") - `disclaimer_label` - **Start / end dates** (ISO 8601) - **Categories**, `gated_type`, `state_media_run_label`, `contains_digital_created_media` ### Filters supported (verified) | Filter | Values | Verified? | |---|---|---| | **Keyword** | any string | ✓ (`nike`, `allbirds`, `climate`) | | **Page ID** | Facebook Page IDs (one or many) | ✓ (Nike page 15087023444 returns historical ads) | | **Country** | ISO-2 codes, multi-country support | ✓ (US, GB, DE tested) | | **Active status** | `active` / `inactive` / `all` | ✓ | | **Ad type** | `ALL` / `POLITICAL_AND_ISSUE_ADS` / `EMPLOYMENT_ADS` / `HOUSING_ADS` / `CREDIT_ADS` | ✓ political ads return spend + impressions | | **Media type** | `all` / `image` / `video` / `meme` | ✓ video-only filter verified | | **Publisher platforms** | `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `AUDIENCE_NETWORK` | API accepts | | **Content languages** | ISO codes | API accepts | | **Pagination** | opaque cursor via `page_info.end_cursor` | ✓ multi-page pull verified | ### Run modes | Mode | Behavior | |---|---| | `search` (default) | Keyword search across the chosen countries | | `advertiser` | Pass `pageIds` to audit every ad a given Page is or was running | | `multi_country` | Same keyword across many countries — output tagged with `country` | ### Example inputs #### 1. Daily Nike spy in 3 markets ```json { "mode": "search", "queries": ["nike"], "countries": ["US", "GB", "DE"], "activeStatus": "active", "maxAdsPerQuery": 200 } ```` #### 2. Full audit of one advertiser ```json { "mode": "advertiser", "pageIds": ["15087023444"], "countries": ["US"], "activeStatus": "all", "maxAdsPerQuery": 1000 } ``` #### 3. Political ad watch in the US ```json { "mode": "search", "queries": ["climate", "election"], "countries": ["US"], "adType": "POLITICAL_AND_ISSUE_ADS", "maxAdsPerQuery": 500 } ``` #### 4. Video-only beauty creative bank ```json { "mode": "search", "queries": ["skincare", "makeup", "fragrance"], "countries": ["US", "GB"], "mediaType": "video", "maxAdsPerQuery": 100 } ``` ### How it works Meta's Ad Library is publicly accessible but its frontend exchanges a short anti-bot handshake before serving the data: 1. Actor GETs `/ads/library/?…`. If Meta returns a 403 challenge page (`__rd_verify_…`), the actor POSTs the challenge URL once and re-GETs. This is a documented public handshake; no login or credentials are involved. 2. The actor extracts `lsd` + a few session tokens from the resulting HTML. 3. Every ad-listing query goes to `POST /api/graphql/` with `fb_api_req_friendly_name=AdLibrarySearchPaginationQuery` and the official `doc_id`. The same query name the Ad Library UI uses. 4. Pagination uses Meta's own `page_info.end_cursor`. Because everything is plain HTTP, runs are fast (~1-3 seconds per ~30-ad page) and memory-light. ### Pricing (PAY\_PER\_EVENT) | Event | Price | |---|---| | Actor start | $0.005 | | Per (keyword × country × filter) combo swept | $0.005 | | Per ad row extracted | $0.0005 | A typical run pulling 200 ads/country in 3 countries (US/GB/DE) = **~$0.32**. A full advertiser audit pulling 1,000 ads in one country = **~$0.51**. ### Ethics The Meta Ad Library is a public transparency service Meta is required to publish under the EU DSA and various national laws. The actor accesses only publicly displayed information, holds no login session, and observes Meta's expected client handshake. It does not access user content, private posts, or any data behind authentication. ### License MIT. # Actor input Schema ## `mode` (type: `string`): search: keyword search; advertiser: by Page IDs; multi\_country: same keyword across many countries. ## `queries` (type: `array`): One or more keywords (for `search`/`multi_country`). Ignored in `advertiser` mode. ## `pageIds` (type: `array`): Facebook Page IDs to audit. Find a Page ID via the Ad Library search → click an advertiser → URL contains view\_all\_page\_id=. ## `countries` (type: `array`): ISO-2 country codes. Common: US, GB, DE, FR, IT, ES, NL, BR, JP, IN, MX, CA, AU. Pass ALL for global. ## `activeStatus` (type: `string`): Filter by whether the ad is currently running. ## `adType` (type: `string`): ALL = every ad. The other options surface only ads classified into Meta's regulated categories (political, employment, housing, credit), which include spend & impressions disclosure. ## `mediaType` (type: `string`): Filter by creative media type. ## `publisherPlatforms` (type: `array`): Empty = all. Otherwise pick from FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE\_NETWORK. ## `contentLanguages` (type: `array`): Language ISO codes (en, es, de, fr, pt, ja, ar, …). Empty = all languages. ## `maxAdsPerQuery` (type: `integer`): Caps each Cartesian-product combo. The actor paginates until this is reached or the source returns no more. ## `pageSize` (type: `integer`): How many ads to ask for per GraphQL call. 30 matches the UI; larger values may be capped server-side. ## `proxyConfiguration` (type: `object`): REQUIRED for cloud runs — Meta rate-limits datacenter IPs. Use Apify Proxy with RESIDENTIAL group for reliable access. ## `maxConcurrency` (type: `integer`): Max parallel (keyword × country) combos. ## Actor input object example ```json { "mode": "search", "queries": [ "nike", "allbirds" ], "pageIds": [], "countries": [ "US" ], "activeStatus": "active", "adType": "ALL", "mediaType": "all", "publisherPlatforms": [], "contentLanguages": [], "maxAdsPerQuery": 100, "pageSize": 30, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] }, "maxConcurrency": 3 } ``` # 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 = { "queries": [ "nike", "allbirds" ], "countries": [ "US" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("buff_pineapple/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 = { "queries": [ "nike", "allbirds", ], "countries": ["US"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("buff_pineapple/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 '{ "queries": [ "nike", "allbirds" ], "countries": [ "US" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call buff_pineapple/meta-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=buff_pineapple/meta-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper — Facebook + Instagram Ad Spy", "description": "Scrape Meta (Facebook + Instagram) Ad Library globally. No login. Filter by keyword, Page ID, country, ad type, media, platform, language. Returns creative URLs (video HD/SD + images), landing pages, captions, CTA, spend & impressions for political/EU ads.", "version": "0.1", "x-build-id": "v1UTPSZX8MXRNxZZn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/buff_pineapple~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-buff_pineapple-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/buff_pineapple~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-buff_pineapple-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/buff_pineapple~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-buff_pineapple-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", "required": [ "countries" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "advertiser", "multi_country" ], "type": "string", "description": "search: keyword search; advertiser: by Page IDs; multi_country: same keyword across many countries.", "default": "search" }, "queries": { "title": "Keywords", "type": "array", "description": "One or more keywords (for `search`/`multi_country`). Ignored in `advertiser` mode.", "items": { "type": "string" } }, "pageIds": { "title": "Advertiser Page IDs (for `advertiser` mode)", "type": "array", "description": "Facebook Page IDs to audit. Find a Page ID via the Ad Library search → click an advertiser → URL contains view_all_page_id=.", "default": [], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "ISO-2 country codes. Common: US, GB, DE, FR, IT, ES, NL, BR, JP, IN, MX, CA, AU. Pass ALL for global.", "items": { "type": "string" } }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by whether the ad is currently running.", "default": "active" }, "adType": { "title": "Ad type / regulated category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "EMPLOYMENT_ADS", "HOUSING_ADS", "CREDIT_ADS" ], "type": "string", "description": "ALL = every ad. The other options surface only ads classified into Meta's regulated categories (political, employment, housing, credit), which include spend & impressions disclosure.", "default": "ALL" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Filter by creative media type.", "default": "all" }, "publisherPlatforms": { "title": "Publisher platforms", "type": "array", "description": "Empty = all. Otherwise pick from FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK.", "default": [], "items": { "type": "string" } }, "contentLanguages": { "title": "Content languages", "type": "array", "description": "Language ISO codes (en, es, de, fr, pt, ja, ar, …). Empty = all languages.", "default": [], "items": { "type": "string" } }, "maxAdsPerQuery": { "title": "Max ads per (keyword × country × filter) combo", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Caps each Cartesian-product combo. The actor paginates until this is reached or the source returns no more.", "default": 100 }, "pageSize": { "title": "Page size", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many ads to ask for per GraphQL call. 30 matches the UI; larger values may be capped server-side.", "default": 30 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "REQUIRED for cloud runs — Meta rate-limits datacenter IPs. Use Apify Proxy with RESIDENTIAL group for reliable access." }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 15, "type": "integer", "description": "Max parallel (keyword × country) combos.", "default": 3 } } }, "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 } } } } } } } } } } ```