# Meta Ads Library Scraper - Fast & Reliable (`seeb/facebook-ads-library-scraper`) Actor Scrape public Meta/Facebook ads by keyword, copied Ads Library URL, Facebook Page ID, or Ad Library ID. Extract ad text, CTA, platform, creative-format, advertiser, and metadata signals with proxy controls and delivered-row billing. - **URL**: https://apify.com/seeb/facebook-ads-library-scraper.md - **Developed by:** [Techionik](https://apify.com/seeb) (community) - **Categories:** Social media, Lead generation, Automation - **Stats:** 7 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.75 / 1,000 ad rows This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ## Meta Ads Library Scraper - Fast & Reliable Scrape public Meta ads in seconds by copied Ads Library URL, keyword, Facebook Page ID, or Ad Library ID. Get structured ad copy, advertiser, CTA, ad status, start date, placement signals, creative-format signals, direct ad URL, and change-tracking rows for growth teams, agencies, and competitive research. ![Meta Ads Library Scraper hero](./assets/hero.svg) ### Built For - Competitor ad research across Facebook, Instagram, Messenger, WhatsApp, Threads, and Audience Network signals. - Creative research for hooks, offers, CTAs, landing-page angles, and campaign messaging. - Agency lead research by brand, page, niche, product, or keyword. - Scheduled checks for new and updated ads without paying for blocked or empty sources. ### Search Modes - `targetUrl`: paste the full Meta Ads Library URL copied from your browser. This takes priority over all other filters. - `searchQuery`: search by brand, competitor, product, niche, or offer. - `searchQueries`: run multiple keywords in one job. - `pageId`: collect ads from a specific Facebook Page ID. - `adId`: check one specific Meta Ad Library ID. - `adLibraryUrls`: run multiple advanced Ads Library URLs in one job. ### Filters And Controls - Country, ad status, ad type, media type, targeted-country mode, content language, sort mode, and sort direction. - `maxResults` controls the maximum delivered ad rows. - `maxConcurrency` controls speed for multiple keywords or URLs. - `requestHandlerTimeoutSecs` and `maxRunMinutes` stop stalled sessions cleanly. - `monitorChanges` and `onlyChanges` support scheduled new-ad and updated-ad workflows. ### Data Delivered - `libraryId`, `pageName`, `adStatus`, `startedRunning`, `platforms`, `cta`, `creativeFormat`, and `adText`. - Direct `adUrl`, original `sourceUrl`, `searchQuery`, `pageId`, requested ad ID, and scrape timestamp. - `dataQualityScore` and `signalSummary` so rows are easier to sort, review, and export. - Optional raw ad text for audit/debug workflows. - Change rows such as `new_ad` and `updated_ad` when change detection is enabled. ### Proxy Strategy Meta can limit direct browser sessions. Proxy quality is often the difference between a thin sample and a useful ad dataset. For serious runs, use `proxyUrl` with a reliable residential or managed proxy. In the input form, this appears as `Your proxy URL - recommended for highest fill rate`. The actor also supports Apify proxy modes when no custom proxy URL is provided. - `none`: cheapest mode for quick checks. - `auto`: try direct access first, then retry with Apify datacenter proxy if no rows are captured. - `datacenter`: route through Apify datacenter proxy. - `residential`: route through Apify residential proxy, optionally with `proxyCountryCode`. - `proxyUrl`: use a full HTTP, HTTPS, or SOCKS proxy URL from Apify Residential, Bright Data, Oxylabs, or another managed provider. ### Example Input ```json { "searchQuery": "running shoes", "country": "US", "activeStatus": "active", "adType": "all", "mediaType": "all", "maxResults": 100, "maxConcurrency": 1, "requestHandlerTimeoutSecs": 900, "proxyMode": "auto" } ```` ### Example Output ```json { "resultType": "meta_ad", "libraryId": "123456789012345", "pageName": "Example Brand", "adStatus": "active", "startedRunning": "Jun 2026", "platforms": ["Facebook", "Instagram"], "cta": "Shop now", "creativeFormat": "image", "adText": "Visible ad copy from the public Meta Ads Library", "adUrl": "https://www.facebook.com/ads/library/?id=123456789012345", "dataQualityScore": 92, "scrapedAt": "2026-06-24T12:00:00.000Z" } ``` ### Pricing `$10.00 / 1,000 delivered ads` Billing is based on delivered ad rows written to the default dataset. Blocked pages, empty searches, login/captcha pages, timeouts, and no-data sources are stored as notices outside the paid dataset. `maxResults` is a cap, not a promise that Meta will expose that many ads. If Meta exposes 37 useful ads from a 100-ad request, the dataset contains 37 delivered rows. ### Reliability - Browser cleanup after errors. - Whole-run and per-source timeout guards. - Duplicate ad IDs removed before output. - No paid error rows. - Change snapshots stored outside the customer dataset. - Graceful zero-row handling when Meta blocks or exposes no public ads. # Actor input Schema ## `targetUrl` (type: `string`): Full Meta Ads Library URL. When provided, this exact URL is used and the keyword, page, ad, and filter fields are ignored. ## `searchQuery` (type: `string`): Keyword, brand, competitor, product, or offer to search in the public Meta Ads Library. ## `searchQueries` (type: `array`): Optional extra keywords or brand names. Use this to collect more ad rows in one run. ## `pageId` (type: `string`): Optional Facebook Page ID for advertiser/page-level ad discovery. ## `adId` (type: `string`): Optional Meta Ad Library ID for checking one specific ad. ## `adLibraryUrls` (type: `array`): Optional full Meta Ads Library URLs. Use this for multiple advanced searches copied from the Ads Library UI. ## `country` (type: `string`): Two-letter country code for keyword, page, and ad searches. ## `activeStatus` (type: `string`): Choose active ads, inactive ads, or all ads. ## `adType` (type: `string`): Meta Ads Library ad category filter. ## `mediaType` (type: `string`): Filter ads by media type where Meta exposes the filter publicly. ## `isTargetedCountry` (type: `boolean`): Limit results to ads Meta identifies as targeted to the selected country. ## `contentLanguages` (type: `array`): Optional language codes such as en, es, de, fr, or ar. ## `sortMode` (type: `string`): Preferred Meta Ads Library sort mode for URL-based searches. ## `sortDirection` (type: `string`): Sort direction for supported Meta Ads Library views. ## `maxResults` (type: `integer`): Maximum useful ad rows to write to the dataset. Billing is based on delivered rows, not requested rows. ## `maxConcurrency` (type: `integer`): Number of Ad Library sources to process in parallel. Keep at 1 for safest runs; increase for many keywords or URLs. ## `requestHandlerTimeoutSecs` (type: `integer`): Maximum seconds spent on each query, page, ad, or target URL. ## `monitorChanges` (type: `boolean`): Save snapshots and compare ad IDs, status, text, and start date across scheduled runs. ## `onlyChanges` (type: `boolean`): When change detection is enabled, output only new or updated ad rows. ## `proxyUrl` (type: `string`): Optional full HTTP, HTTPS, or SOCKS proxy URL. For serious Meta Ads Library scraping, use a reliable residential or managed proxy to improve capture rate when Meta blocks direct browser sessions. ## `proxyMode` (type: `string`): Fallback Apify proxy mode used only when Custom proxy URL is empty. ## `proxyCountryCode` (type: `string`): Optional two-letter country code for Apify residential proxy mode. ## `includeRawText` (type: `boolean`): Include the raw text block used for parsing each ad row. ## `maxRunMinutes` (type: `integer`): Whole-run cost guard. The Actor stops cleanly instead of waiting forever when Meta stalls or blocks loading. ## Actor input object example ```json { "targetUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered", "searchQuery": "running shoes", "searchQueries": [ "adidas", "puma", "reebok" ], "pageId": "", "adId": "", "adLibraryUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shopify&search_type=keyword_unordered" ], "country": "US", "activeStatus": "active", "adType": "all", "mediaType": "all", "isTargetedCountry": false, "contentLanguages": [], "sortMode": "total_impressions", "sortDirection": "desc", "maxResults": 100, "maxConcurrency": 1, "requestHandlerTimeoutSecs": 900, "monitorChanges": false, "onlyChanges": false, "proxyUrl": "http://groups-RESIDENTIAL:YOUR_APIFY_TOKEN@proxy.apify.com:8000", "proxyMode": "none", "proxyCountryCode": "", "includeRawText": false, "maxRunMinutes": 12 } ``` # Actor output Schema ## `results` (type: `string`): Normal runs contain delivered ad rows. When Output only changes is enabled, rows contain new or updated ad events. # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("seeb/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 = {} # Run the Actor and wait for it to finish run = client.actor("seeb/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 '{}' | apify call seeb/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=seeb/facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ads Library Scraper - Fast & Reliable", "description": "Scrape public Meta/Facebook ads by keyword, copied Ads Library URL, Facebook Page ID, or Ad Library ID. Extract ad text, CTA, platform, creative-format, advertiser, and metadata signals with proxy controls and delivered-row billing.", "version": "0.2", "x-build-id": "8KVi6NbHsMgwgrmuZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/seeb~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-seeb-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/seeb~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-seeb-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/seeb~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-seeb-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", "properties": { "targetUrl": { "title": "Target URL", "type": "string", "description": "Full Meta Ads Library URL. When provided, this exact URL is used and the keyword, page, ad, and filter fields are ignored.", "default": "" }, "searchQuery": { "title": "Search query", "type": "string", "description": "Keyword, brand, competitor, product, or offer to search in the public Meta Ads Library.", "default": "nike" }, "searchQueries": { "title": "Additional search queries", "type": "array", "description": "Optional extra keywords or brand names. Use this to collect more ad rows in one run.", "default": [], "items": { "type": "string" } }, "pageId": { "title": "Facebook page ID", "type": "string", "description": "Optional Facebook Page ID for advertiser/page-level ad discovery.", "default": "" }, "adId": { "title": "Ad Library ID", "type": "string", "description": "Optional Meta Ad Library ID for checking one specific ad.", "default": "" }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Optional full Meta Ads Library URLs. Use this for multiple advanced searches copied from the Ads Library UI.", "default": [], "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for keyword, page, and ad searches.", "default": "US" }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Choose active ads, inactive ads, or all ads.", "default": "active" }, "adType": { "title": "Ad type", "enum": [ "all", "political_and_issue_ads", "housing", "employment", "credit" ], "type": "string", "description": "Meta Ads Library ad category filter.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Filter ads by media type where Meta exposes the filter publicly.", "default": "all" }, "isTargetedCountry": { "title": "Targeted country only", "type": "boolean", "description": "Limit results to ads Meta identifies as targeted to the selected country.", "default": false }, "contentLanguages": { "title": "Content languages", "type": "array", "description": "Optional language codes such as en, es, de, fr, or ar.", "default": [], "items": { "type": "string" } }, "sortMode": { "title": "Sort mode", "enum": [ "total_impressions", "relevance", "start_date" ], "type": "string", "description": "Preferred Meta Ads Library sort mode for URL-based searches.", "default": "total_impressions" }, "sortDirection": { "title": "Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Sort direction for supported Meta Ads Library views.", "default": "desc" }, "maxResults": { "title": "Max ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum useful ad rows to write to the dataset. Billing is based on delivered rows, not requested rows.", "default": 100 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of Ad Library sources to process in parallel. Keep at 1 for safest runs; increase for many keywords or URLs.", "default": 1 }, "requestHandlerTimeoutSecs": { "title": "Timeout per source", "minimum": 60, "maximum": 1200, "type": "integer", "description": "Maximum seconds spent on each query, page, ad, or target URL.", "default": 900 }, "monitorChanges": { "title": "Detect changes", "type": "boolean", "description": "Save snapshots and compare ad IDs, status, text, and start date across scheduled runs.", "default": false }, "onlyChanges": { "title": "Output only changes", "type": "boolean", "description": "When change detection is enabled, output only new or updated ad rows.", "default": false }, "proxyUrl": { "title": "Your proxy URL - recommended for highest fill rate", "type": "string", "description": "Optional full HTTP, HTTPS, or SOCKS proxy URL. For serious Meta Ads Library scraping, use a reliable residential or managed proxy to improve capture rate when Meta blocks direct browser sessions.", "default": "" }, "proxyMode": { "title": "Apify proxy mode", "enum": [ "none", "auto", "datacenter", "residential" ], "type": "string", "description": "Fallback Apify proxy mode used only when Custom proxy URL is empty.", "default": "none" }, "proxyCountryCode": { "title": "Residential proxy country", "type": "string", "description": "Optional two-letter country code for Apify residential proxy mode.", "default": "" }, "includeRawText": { "title": "Include raw ad text", "type": "boolean", "description": "Include the raw text block used for parsing each ad row.", "default": false }, "maxRunMinutes": { "title": "Max run minutes", "minimum": 1, "maximum": 20, "type": "integer", "description": "Whole-run cost guard. The Actor stops cleanly instead of waiting forever when Meta stalls or blocks loading.", "default": 12 } } }, "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 } } } } } } } } } } ```