# Facebook Ads Library Scraper (`fetch_cat/facebook-ads-library-scraper`) Actor Scrape public Meta/Facebook Ads Library ads by keyword, page, country, status, and media for competitive ad intelligence. - **URL**: https://apify.com/fetch\_cat/facebook-ads-library-scraper.md - **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community) - **Categories:** Social media, Marketing, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.28 / 1,000 item extracteds 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 ## Facebook Ads Library Scraper Track public Meta and Facebook ads without building your own browser automation. This actor searches the public Meta Ads Library by keyword or advertiser page and saves structured ad records for competitive intelligence, brand monitoring, market research, and reporting workflows. Use it to collect public ad copy, advertiser names, library IDs, status, delivery dates, platforms, creative media URLs when exposed, landing links, and snapshot links from Facebook Ads Library. ### What does Facebook Ads Library Scraper do? Facebook Ads Library Scraper helps you turn public ad search pages into a clean dataset. - ๐Ÿ”Ž Search public ads by keyword such as a brand, product, category, or campaign topic. - ๐Ÿข Search advertiser/page ads when you have a Facebook Page ID or supported page URL. - ๐ŸŒ Filter by country code such as `US`, `GB`, `DE`, or `FR`. - โœ… Choose active, inactive, or all public ads. - ๐Ÿ–ผ๏ธ Filter by media type when Meta exposes the option. - ๐Ÿ“ฆ Export results as JSON, CSV, Excel, XML, RSS, or through the Apify API. ### Who is it for? This actor is useful for teams that need public ad intelligence at repeatable intervals. - ๐Ÿ“ฃ Marketing teams tracking competitor messaging. - ๐Ÿงช Growth teams testing positioning across markets. - ๐Ÿงพ Agencies preparing client competitor reports. - ๐Ÿ›ก๏ธ Brand monitors watching impersonation or risky ad claims. - ๐ŸŽ“ Researchers studying public advertising trends. - ๐Ÿงฐ Data teams feeding ad examples into dashboards and AI workflows. ### Why use it? The Meta Ads Library website is built for browsing. It is not convenient when you need a repeatable table of public ads. This actor packages the workflow into an Apify actor so you can schedule it, call it from an API, and combine the output with the rest of your data stack. ### What data can you extract? | Field | Description | | --- | --- | | `query` | Keyword used for the run, when keyword mode is used. | | `country` | Country filter used for the search. | | `advertiserName` | Advertiser or page name visible on the ad card. | | `advertiserPageUrl` | Public advertiser page URL when exposed. | | `libraryId` | Meta Ads Library ID for the public ad. | | `adStatus` | Active or inactive status when visible. | | `startedAt` | Start date text when visible. | | `endedAt` | End date text when visible. | | `platforms` | Meta platforms detected in the card text. | | `adText` | Main visible ad copy. | | `caption` | Optional caption field. | | `adTitle` | Short visible title/headline when detected. | | `creativeType` | Image, video, or unknown. | | `imageUrls` | Creative image URLs when exposed in the page. | | `videoUrls` | Creative video URLs when exposed in the page. | | `landingUrl` | Destination URL when visible. | | `snapshotUrl` | Meta Ads Library snapshot URL. | | `sourceUrl` | Ads Library search URL used for extraction. | | `scrapedAt` | ISO timestamp when the item was scraped. | ### Pricing This Actor uses Apify pay-per-event pricing. The prices below come from the current Actor pricing configuration. Apify public plans map to Store discount tiers, so the table shows both the user-facing plan context and the pricing tier name. The final price shown in Apify depends on the user account plan and any custom agreement. | Event | What is charged | Price | | --- | --- | ---: | | `start` | One-time fee charged when a run starts. Covers fixed startup cost (init, proxy warmup, first HTTP setup). | $0.005 | | Event | What is charged | Free / no discount | Starter / Bronze | Scale / Silver | Business / Gold | Custom / Platinum | Custom / Diamond | | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | | `item` | Charged per item extracted. | $0.5355 / 1,000 | $0.46565 / 1,000 | $0.36321 / 1,000 | $0.27939 / 1,000 | $0.18626 / 1,000 | $0.13038 / 1,000 | Apify may also charge platform usage for compute, storage, proxies, or data transfer outside this Actor pricing. Check the Actor run and the Apify Pricing tab for the exact cost shown to your account. ### Quick start 1. Open the actor on Apify. 2. Enter a keyword such as `coffee` or a known advertiser page ID. 3. Choose a country such as `US`. 4. Keep `maxItems` low for the first run. 5. Start the actor. 6. Download the dataset or call it through the API. ### Input options #### Keyword query Use `query` to search public ads by text. Enter one keyword, or separate multiple keywords with commas/new lines when you want one combined export. Examples: - `nike` - `coffee` - `running shoes` - `meal delivery` - `coffee, nike, travel` #### Advertiser page URL or page ID Use `pageId` when you know the numeric Facebook Page ID. Some page URLs also contain an ID and can be passed as `advertiserPageUrl`. #### Country Use a two-letter Ads Library country code. The default is `US`. #### Ad status Choose one of: - `active` - `inactive` - `all` #### Ad type The default is `all`. Political and issue ads are available through the dedicated option where supported by Meta. #### Media type Choose all media, image, video, memes, image and meme, or no-media results. #### Date range Use optional `startDate` and `endDate` in `YYYY-MM-DD` format when you need a delivery date window. #### Maximum ads `maxItems` controls how many records are saved. Start with 10 and increase gradually. #### Proxy configuration Leave proxy settings empty for direct access. If Meta shows verification or empty pages for your run, enable Apify Proxy and choose the lowest-cost proxy group that works for your target country. ### Example input ```json { "query": "coffee", "country": "US", "activeStatus": "active", "adType": "all", "mediaType": "all", "maxItems": 10 } ```` ### Example output ```json { "query": "coffee", "country": "US", "advertiserName": "Example Coffee", "advertiserPageUrl": "https://www.facebook.com/example", "libraryId": "1234567890", "adStatus": "Active", "startedAt": "Jan 1, 2026", "endedAt": null, "platforms": ["Facebook", "Instagram"], "adText": "Try our new roast today.", "caption": null, "adTitle": "New roast", "creativeType": "image", "imageUrls": ["https://..."], "videoUrls": [], "landingUrl": "https://example.com", "snapshotUrl": "https://www.facebook.com/ads/library/?id=1234567890", "sourceUrl": "https://www.facebook.com/ads/library/...", "scrapedAt": "2026-07-03T00:00:00.000Z" } ``` ### Tips for better results - Use specific brand or product terms instead of very broad terms. - Match the country to the market you are researching. - Use `active` for current competitive monitoring. - Use `all` when building historical examples. - Increase `maxItems` only after a small run succeeds. - Keep separate runs for different brands so exports stay easy to compare. ### Scheduling You can schedule the actor in Apify to run daily, weekly, or monthly. Common schedules include: - Daily brand monitoring. - Weekly competitor ad review. - Monthly creative swipe-file export. - Campaign launch monitoring during a specific date range. ### Integrations Use the dataset output with: - Google Sheets exports for quick reporting. - BI dashboards for competitor trend tracking. - Slack or email alerts through Apify integrations. - Webhooks that trigger when a run finishes. - Data warehouses through Apify API calls. - AI analysis pipelines that summarize ad themes. ### API usage #### Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('fetch_cat/facebook-ads-library-scraper').call({ query: 'coffee', country: 'US', activeStatus: 'active', maxItems: 10, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('fetch_cat/facebook-ads-library-scraper').call(run_input={ 'query': 'coffee', 'country': 'US', 'activeStatus': 'active', 'maxItems': 10, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~facebook-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"query":"coffee","country":"US","activeStatus":"active","maxItems":10}' ``` ### MCP usage Use Apify MCP with Claude Desktop or Claude Code to run the actor from natural language prompts. MCP URL: ```text https://mcp.apify.com/?tools=fetch_cat/facebook-ads-library-scraper ``` Claude Code setup: ```bash claude mcp add apify-facebook-ads-library https://mcp.apify.com/?tools=fetch_cat/facebook-ads-library-scraper ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-facebook-ads-library": { "url": "https://mcp.apify.com/?tools=fetch_cat/facebook-ads-library-scraper" } } } ``` Example prompts: - "Run Facebook Ads Library Scraper for coffee ads in the US and summarize the top messages." - "Collect 20 active ads for this advertiser page ID and group the copy themes." - "Compare Facebook and Instagram platform mentions in the latest dataset." ### Legality Facebook Ads Library Scraper is intended for public ad transparency data. Use the actor responsibly, respect applicable laws and platform rules, and avoid collecting private account data or attempting to bypass access controls. ### Legal and ethical notes This actor is designed for public Ads Library data. Do not use it to collect private account data, bypass access controls, or violate Meta's terms. Review your use case, jurisdiction, and compliance obligations before using scraped data in production. ### Troubleshooting #### The run returns no ads The query may have no public ads in the selected country/status combination. Try a broader keyword, a different country, or `activeStatus: all`. #### Meta shows verification Try Apify Proxy, lower `maxItems`, or run again later. Verification pages can happen on public sites with automated traffic. #### Advertiser page URL does not work Use a numeric `pageId` if the URL does not contain one. Vanity page URLs do not always expose a numeric ID. ### Limits - This actor does not log in to Facebook. - Some fields are only saved when visible in the public card. - Creative URLs may expire or vary by region. - Very broad searches may require multiple runs split by country or date range. ### Related scrapers Explore related actors from the same catalog: - https://apify.com/fetch\_cat/facebook-pages-scraper - https://apify.com/fetch\_cat/instagram-stories-highlights-scraper - https://apify.com/fetch\_cat/instagram-profile-posts-scraper - https://apify.com/fetch\_cat/linkedin-jobs-scraper ### Support If you need a field that appears in the Ads Library page but is missing from the dataset, open an issue with a sample run and the public ad snapshot URL. ### FAQ #### Can I scrape inactive ads? Yes. Set `activeStatus` to `inactive` or `all`. #### Can I use it without a Facebook account? Yes. The actor is designed for public Ads Library pages and does not accept credentials. #### Can I run it every day? Yes. Use Apify schedules and keep inputs focused for predictable costs. #### Does it include Instagram ads? When Meta exposes platform labels on the ad card, the `platforms` field can include Instagram. #### Can I export to CSV? Yes. Apify datasets can be downloaded as CSV, JSON, Excel, XML, RSS, and HTML. # Actor input Schema ## `query` (type: `string`): Keyword to search in public Ads Library, for example a brand, product, or topic. Separate multiple keywords with commas or new lines for one combined export. ## `advertiserPageUrl` (type: `string`): Optional Facebook Page URL for advertiser/page mode. Use either a keyword query or a page URL/page ID. ## `pageId` (type: `string`): Optional Facebook Page ID for advertiser/page mode. ## `country` (type: `string`): Two-letter Meta Ads Library country code. ## `activeStatus` (type: `string`): Filter by active, inactive, or all ads. ## `adType` (type: `string`): Meta Ads Library ad type filter. ## `mediaType` (type: `string`): Creative media filter. ## `startDate` (type: `string`): Optional lower bound for ad delivery start date in YYYY-MM-DD format. ## `endDate` (type: `string`): Optional upper bound for ad delivery date in YYYY-MM-DD format. ## `maxItems` (type: `integer`): Maximum number of ad records to save. ## `proxyConfiguration` (type: `object`): Optional proxy settings. Leave empty for direct access; enable Apify Proxy if Meta shows verification or empty pages. ## Actor input object example ```json { "query": "coffee", "country": "US", "activeStatus": "active", "adType": "all", "mediaType": "all", "maxItems": 10 } ``` # 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 = { "query": "coffee", "country": "US", "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("fetch_cat/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 = { "query": "coffee", "country": "US", "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("fetch_cat/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 '{ "query": "coffee", "country": "US", "maxItems": 10 }' | apify call fetch_cat/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fetch_cat/facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Scrape public Meta/Facebook Ads Library ads by keyword, page, country, status, and media for competitive ad intelligence.", "version": "0.1", "x-build-id": "NaDc0KWtqkK87Hirr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetch_cat~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetch_cat-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/fetch_cat~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-fetch_cat-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/fetch_cat~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-fetch_cat-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": { "query": { "title": "Keyword query", "type": "string", "description": "Keyword to search in public Ads Library, for example a brand, product, or topic. Separate multiple keywords with commas or new lines for one combined export." }, "advertiserPageUrl": { "title": "Advertiser page URL", "type": "string", "description": "Optional Facebook Page URL for advertiser/page mode. Use either a keyword query or a page URL/page ID." }, "pageId": { "title": "Advertiser page ID", "type": "string", "description": "Optional Facebook Page ID for advertiser/page mode." }, "country": { "title": "Country", "type": "string", "description": "Two-letter Meta Ads Library country code.", "default": "US" }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by active, inactive, or all ads.", "default": "active" }, "adType": { "title": "Ad type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Meta Ads Library ad type filter.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "memes", "image_and_meme", "none" ], "type": "string", "description": "Creative media filter.", "default": "all" }, "startDate": { "title": "Start date", "type": "string", "description": "Optional lower bound for ad delivery start date in YYYY-MM-DD format." }, "endDate": { "title": "End date", "type": "string", "description": "Optional upper bound for ad delivery date in YYYY-MM-DD format." }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of ad records to save.", "default": 10 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy settings. Leave empty for direct access; enable Apify Proxy if Meta shows verification or empty pages." } } }, "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 } } } } } } } } } } ```