# Meta Ads Library Scraper - Creative Intelligence (`glowing_glove/meta-facebook-ads-library-scraper`) Actor Scrape public Meta/Facebook ads by keyword, URL, page ID, or ad ID with proxy controls, strict timeouts, clean ad rows, and change snapshots. - **URL**: https://apify.com/glowing\_glove/meta-facebook-ads-library-scraper.md - **Developed by:** [Ushba Khan](https://apify.com/glowing_glove) (community) - **Categories:** Social media, Lead generation, Automation - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 meta ad results 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 Ads Library Scraper - Creative Intelligence Collect public Meta ad intelligence from Ads Library URLs, keywords, Facebook Page IDs, and specific Ad Library IDs. The actor is built for competitor tracking, agency prospecting, creative research, and scheduled ad discovery with clean delivered-row output. ![Meta Ads Library Scraper hero](./assets/hero.svg) ### Built For - Finding active ads by brand, niche, keyword, or advertiser page. - Studying hooks, CTAs, creative-format signals, offers, platforms, and campaign timing. - Building lead lists from advertisers already spending on Meta. - Running scheduled checks for new or changed public ads. ### Input Modes - `targetUrl`: use the exact Meta Ads Library URL from your browser. - `searchQuery` and `searchQueries`: search one or many brands, products, offers, or competitor terms. - `pageId`: collect ads for one advertiser page. - `adId`: inspect a single Ad Library ID. - `adLibraryUrls`: process multiple copied Ads Library URLs in the same run. ### Filters - Country. - Active, inactive, or all ads. - Ad category: all, political/issue, housing, employment, or credit. - Media type: all, image, video, or meme. - Targeted-country mode. - Content language filters. - Sort mode and direction where Meta exposes those controls. ### Data Delivered - Ad Library ID, advertiser/page name, activity state, started-running date, CTA, creative format, and platform signals. - Parsed visible ad text and optional raw text. - Direct ad URL and original source URL for review. - `dataQualityScore`, `signalSummary`, and timestamp. - New-ad and updated-ad rows when change detection is enabled. ### Proxy And Speed Controls Use direct mode for cheap checks. Proxy quality is often the difference between a thin sample and a useful ad dataset. Use `proxyUrl` with a reliable residential or managed proxy for serious collection. In the input form, this is the `Your proxy URL - recommended for highest fill rate` field. If no custom proxy is supplied, Apify proxy modes can route direct, auto fallback, datacenter, or residential sessions. Keep `maxConcurrency` at `1` for highest stability on large Meta searches. Increase it only when processing multiple keywords or URLs with enough memory. `requestHandlerTimeoutSecs` and `maxRunMinutes` protect the run from hanging pages. ### Example Input ```json { "targetUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shopify&search_type=keyword_unordered", "maxResults": 100, "maxConcurrency": 1, "requestHandlerTimeoutSecs": 900, "proxyMode": "auto", "monitorChanges": false } ```` ### Example Output ```json { "resultType": "meta_ad", "libraryId": "123456789012345", "pageName": "Example Advertiser", "adStatus": "active", "platforms": ["Facebook", "Instagram"], "cta": "Learn more", "creativeFormat": "video", "adText": "Visible public ad copy", "adUrl": "https://www.facebook.com/ads/library/?id=123456789012345", "sourceUrl": "https://www.facebook.com/ads/library/", "dataQualityScore": 92, "scrapedAt": "2026-06-24T12:00:00.000Z" } ``` ### Pricing `$10.00 / 1,000 delivered ads` Only valid ad rows written to the default dataset count as delivered ads. Empty searches, blocked pages, login/captcha pages, timeouts, and no-data cases are saved as notices outside the customer dataset. ### Reliability - Direct URL validation. - Per-source and whole-run timeout guards. - Browser cleanup after failures. - Duplicate ad IDs removed before output. - No paid error rows. - Change snapshots stored outside the paid dataset. # 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": 25, "maxConcurrency": 1, "requestHandlerTimeoutSecs": 120, "monitorChanges": false, "onlyChanges": false, "proxyUrl": "http://groups-RESIDENTIAL:YOUR_APIFY_TOKEN@proxy.apify.com:8000", "proxyMode": "none", "proxyCountryCode": "", "includeRawText": false, "maxRunMinutes": 4 } ``` # 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("glowing_glove/meta-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("glowing_glove/meta-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 glowing_glove/meta-facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=glowing_glove/meta-facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ads Library Scraper - Creative Intelligence", "description": "Scrape public Meta/Facebook ads by keyword, URL, page ID, or ad ID with proxy controls, strict timeouts, clean ad rows, and change snapshots.", "version": "0.2", "x-build-id": "61Mo2s37gNh7olNCk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/glowing_glove~meta-facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-glowing_glove-meta-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/glowing_glove~meta-facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-glowing_glove-meta-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/glowing_glove~meta-facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-glowing_glove-meta-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": 25 }, "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": 120 }, "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": 4 } } }, "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 } } } } } } } } } } ```