# Meta Ad Library Page Resolver (`automation-lab/meta-ad-library-page-resolver`) Actor Resolve brands, domains, Facebook Pages, and Ad Library URLs to Meta advertiser page IDs and page-specific Ad Library URLs. - **URL**: https://apify.com/automation-lab/meta-ad-library-page-resolver.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Marketing - **Stats:** 3 total users, 2 monthly users, 73.3% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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 Ad Library Page Resolver Resolve brands, company domains, Facebook Page URLs, and existing Meta Ad Library links into page IDs you can use in Meta/Facebook ad research workflows. ### What does Meta Ad Library Page Resolver do? Meta Ad Library Page Resolver turns messy advertiser inputs into clean Meta Ad Library page targets. You can submit: - ๐Ÿ”Ž Brand names such as `Nike` or `Patagonia` - ๐ŸŒ Company domains such as `apple.com` - ๐Ÿ“˜ Facebook Page URLs such as `https://www.facebook.com/nike` - ๐Ÿงญ Existing Meta Ad Library search URLs The actor returns resolved advertiser page IDs, page names, Facebook Page URLs, page-specific Meta Ad Library URLs, ranking signals, and evidence ad IDs. ### Who is it for? This resolver is built for paid-social and competitive-intelligence teams that need clean page IDs before scraping ads. - ๐Ÿง‘โ€๐Ÿ’ผ Paid-social agencies mapping a client or competitor list to advertiser pages - ๐Ÿ•ต๏ธ Competitive-intel teams preparing monitoring seeds - ๐Ÿงพ Compliance and reputation teams auditing brand impersonation or regulated ads - ๐Ÿงฐ Data teams enriching CRM or domain lists with Meta advertiser identifiers - ๐Ÿ“ˆ Growth teams building repeatable ad-library research pipelines ### Why use it? Meta Ad Library workflows usually need a page ID or a precise page-specific URL. Brand names and domains are ambiguous. This actor handles the resolver step so your downstream ad scraping starts with better seeds. ### Typical workflow 1. Paste brand names, domains, or Facebook Page URLs. 2. Select a country and optional ad status. 3. Run the actor. 4. Export resolved `pageId` and `metaAdLibraryUrl` values. 5. Feed those URLs into [`facebook-ads-library`](https://apify.com/automation-lab/facebook-ads-library) or your monitoring system. ### Data returned | Field | Description | | --- | --- | | `query` | Original normalized query used for resolution | | `inputType` | Query, domain, Facebook Page URL, or Ad Library URL | | `rank` | Match rank for this input | | `pageName` | Resolved advertiser page name | | `pageId` | Meta/Facebook page ID | | `facebookPageUrl` | Public Facebook Page URL | | `metaAdLibraryUrl` | Page-specific Meta Ad Library URL | | `matchScore` | Simple score based on query/name similarity | | `activeAdCount` | Estimate from inspected ads when enabled | | `matchedFromAdArchiveIds` | Evidence ad IDs used for the match | ### How much does it cost to resolve Meta Ad Library page IDs? The actor uses pay-per-event pricing: - A small start charge per run - A per-result charge for each resolved page record Use low `maxMatchesPerQuery` and `maxAdsToInspect` values for cheap first tests. Increase them when you need more recall across ambiguous brands. ### Input options #### Brand, advertiser, or domain queries Use `queries` for brand names and domains. Domains are normalized into likely brand names, for example `apple.com` becomes `apple`. #### Facebook Page URLs Use `pageUrls` when you already have Facebook pages. Numeric `profile.php?id=` URLs are resolved directly. Named slugs are searched in Meta Ad Library. #### Meta Ad Library URLs Use `adsLibraryUrls` to normalize and inspect an existing search or page URL. #### Country and filters `country`, `activeStatus`, and `mediaType` are passed through to Meta Ad Library. Start with `US` and `all` unless you know your target market. ### Output example ```json { "query": "nike", "inputType": "query", "rank": 1, "pageName": "Nike", "pageId": "15087023444", "facebookPageUrl": "https://www.facebook.com/nike/", "metaAdLibraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&media_type=all&view_all_page_id=15087023444&search_type=page", "matchScore": 100, "activeAdCount": 1 } ```` ### Tips for better matching - Use exact brand names when possible. - Add the official domain for brand disambiguation. - Use `maxMatchesPerQuery: 3` for broad discovery. - Use `maxMatchesPerQuery: 1` for enrichment pipelines. - Raise `maxAdsToInspect` only when you need more possible pages. ### Integrations Use this actor before: - [`facebook-ads-library`](https://apify.com/automation-lab/facebook-ads-library) for ad scraping by page ID - Brand monitoring pipelines that need stable advertiser identifiers - CRM enrichment workflows that start from company domains - BI dashboards tracking paid-social activity by advertiser page ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/meta-ad-library-page-resolver').call({ queries: ['nike', 'apple.com'], country: 'US', maxMatchesPerQuery: 2, maxAdsToInspect: 20 }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/meta-ad-library-page-resolver').call(run_input={ 'queries': ['nike', 'apple.com'], 'country': 'US', 'maxMatchesPerQuery': 2, 'maxAdsToInspect': 20, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~meta-ad-library-page-resolver/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"queries":["nike","apple.com"],"country":"US","maxMatchesPerQuery":2}' ``` ### MCP usage You can connect the actor to Claude through Apify MCP: `https://mcp.apify.com/?tools=automation-lab/meta-ad-library-page-resolver` Claude Code setup: ```bash claude mcp add apify-meta-page-resolver https://mcp.apify.com/?tools=automation-lab/meta-ad-library-page-resolver ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-meta-page-resolver": { "url": "https://mcp.apify.com/?tools=automation-lab/meta-ad-library-page-resolver" } } } ``` Example prompts: - "Resolve these competitor domains to Meta Ad Library page IDs." - "Find page-specific Ad Library URLs for this brand list." - "Prepare page IDs that I can pass to the Facebook Ads Library scraper." ### Reliability notes Meta uses edge protection and dynamic pages. This actor uses a browser/proxy flow rather than plain HTTP. If a query fails, try fewer inputs, a different country, or a more precise brand/domain. ### Limitations The `activeAdCount` field is an estimate from inspected ads, not Meta's full advertiser total. Ambiguous names may return multiple pages. The actor returns evidence IDs so you can review why a page matched. ### Legality Meta Ad Library data is public transparency data. Use the output for lawful research, monitoring, compliance, and competitive analysis. Respect Apify and Meta terms and avoid collecting personal data unnecessarily. ### Troubleshooting #### Why did I get zero matches? The brand may have no ads in the selected country/status, the query may be too broad, or Meta may have returned a temporary challenge. Try `activeStatus: all`, a different country, or the official domain. #### Why are there multiple pages for one brand? Large brands often have regional, product, or franchise pages. Use `rank`, `matchScore`, page name, categories, likes, and evidence ad IDs to choose the right page. ### Related scrapers - [`facebook-ads-library`](https://apify.com/automation-lab/facebook-ads-library) โ€” scrape ads after resolving page IDs - [`facebook-pages-scraper`](https://apify.com/automation-lab/facebook-pages-scraper) โ€” collect public Facebook Page metadata - [`facebook-posts-scraper`](https://apify.com/automation-lab/facebook-posts-scraper) โ€” scrape public Facebook posts ### Changelog #### 0.1 Initial resolver for brand, domain, Facebook Page URL, and Meta Ad Library URL inputs. ### FAQ #### Can I resolve domains directly? Yes. Domains are normalized into likely brand terms and searched in Meta Ad Library. #### Can I feed results into another actor? Yes. Use `metaAdLibraryUrl` or `pageId` with `facebook-ads-library`. #### Does the actor need my Facebook login? No. It uses public Meta Ad Library data and does not require user credentials. #### Is this a full ad scraper? No. It resolves advertiser pages. Use `facebook-ads-library` when you need full ad creative records. ### Example inputs ```json { "queries": ["nike", "apple.com", "patagonia"], "country": "US", "maxMatchesPerQuery": 3, "maxAdsToInspect": 30 } ``` ### Operational guidance For scheduled enrichment, batch 10โ€“25 brands per run and keep `maxMatchesPerQuery` low. For one-off discovery, increase `maxMatchesPerQuery` to review alternatives. # Actor input Schema ## `queries` (type: `array`): Brand names, advertiser names, company domains, or free-form search terms to resolve to Meta Ad Library pages. ## `pageUrls` (type: `array`): Optional Facebook Page URLs. Numeric page/profile IDs are resolved directly; named page URLs are searched by slug. ## `adsLibraryUrls` (type: `array`): Optional existing Meta Ad Library search/page URLs to normalize and inspect for page IDs. ## `country` (type: `string`): Meta Ad Library country code to use for the search. Use ALL for global library searches when supported. ## `activeStatus` (type: `string`): Search all ads, only active ads, or inactive ads when resolving pages. ## `mediaType` (type: `string`): Optional media filter passed to Meta Ad Library. ## `maxMatchesPerQuery` (type: `integer`): Maximum unique advertiser pages to return for each query. ## `maxAdsToInspect` (type: `integer`): How many Ad Library ads to inspect while looking for unique page IDs. Higher values improve recall but cost more. ## `includeActiveAdCount` (type: `boolean`): Return a per-page count based on inspected ads. This is an estimate, not Meta's full page total. ## Actor input object example ```json { "queries": [ "nike", "apple.com", "patagonia" ], "pageUrls": [], "adsLibraryUrls": [], "country": "US", "activeStatus": "all", "mediaType": "all", "maxMatchesPerQuery": 3, "maxAdsToInspect": 20, "includeActiveAdCount": true } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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", "apple.com", "patagonia" ], "pageUrls": [], "adsLibraryUrls": [], "country": "US", "activeStatus": "all", "mediaType": "all", "maxMatchesPerQuery": 3, "maxAdsToInspect": 20, "includeActiveAdCount": true }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/meta-ad-library-page-resolver").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", "apple.com", "patagonia", ], "pageUrls": [], "adsLibraryUrls": [], "country": "US", "activeStatus": "all", "mediaType": "all", "maxMatchesPerQuery": 3, "maxAdsToInspect": 20, "includeActiveAdCount": True, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/meta-ad-library-page-resolver").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", "apple.com", "patagonia" ], "pageUrls": [], "adsLibraryUrls": [], "country": "US", "activeStatus": "all", "mediaType": "all", "maxMatchesPerQuery": 3, "maxAdsToInspect": 20, "includeActiveAdCount": true }' | apify call automation-lab/meta-ad-library-page-resolver --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/meta-ad-library-page-resolver", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ad Library Page Resolver", "description": "Resolve brands, domains, Facebook Pages, and Ad Library URLs to Meta advertiser page IDs and page-specific Ad Library URLs.", "version": "0.1", "x-build-id": "k5y0ZCwcvYFPuDic9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~meta-ad-library-page-resolver/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-meta-ad-library-page-resolver", "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/automation-lab~meta-ad-library-page-resolver/runs": { "post": { "operationId": "runs-sync-automation-lab-meta-ad-library-page-resolver", "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/automation-lab~meta-ad-library-page-resolver/run-sync": { "post": { "operationId": "run-sync-automation-lab-meta-ad-library-page-resolver", "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": { "queries": { "title": "Brand, advertiser, or domain queries", "type": "array", "description": "Brand names, advertiser names, company domains, or free-form search terms to resolve to Meta Ad Library pages.", "items": { "type": "string" } }, "pageUrls": { "title": "Facebook Page URLs", "type": "array", "description": "Optional Facebook Page URLs. Numeric page/profile IDs are resolved directly; named page URLs are searched by slug.", "items": { "type": "string" } }, "adsLibraryUrls": { "title": "Meta Ad Library URLs", "type": "array", "description": "Optional existing Meta Ad Library search/page URLs to normalize and inspect for page IDs.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "IT", "ES", "BR", "IN", "ALL" ], "type": "string", "description": "Meta Ad Library country code to use for the search. Use ALL for global library searches when supported.", "default": "US" }, "activeStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Search all ads, only active ads, or inactive ads when resolving pages.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image_and_meme", "video" ], "type": "string", "description": "Optional media filter passed to Meta Ad Library.", "default": "all" }, "maxMatchesPerQuery": { "title": "Max matches per query", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum unique advertiser pages to return for each query.", "default": 3 }, "maxAdsToInspect": { "title": "Max ads to inspect per query", "minimum": 1, "maximum": 80, "type": "integer", "description": "How many Ad Library ads to inspect while looking for unique page IDs. Higher values improve recall but cost more.", "default": 20 }, "includeActiveAdCount": { "title": "Include active ad count estimate", "type": "boolean", "description": "Return a per-page count based on inspected ads. This is an estimate, not Meta's full page total.", "default": 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 } } } } } } } } } } ```