# Meta Ad Library Scraper — Facebook & Instagram Ads ✅ No Login (`themineworks/meta-ad-library-scraper`) Actor Scrape live ads from the Meta (Facebook & Instagram) Ad Library by keyword or advertiser. Get ad copy, image and video URLs, advertiser, platforms and run dates, and optionally download the creatives. No login. Works in Claude, ChatGPT & any MCP-compatible AI agent. - **URL**: https://apify.com/themineworks/meta-ad-library-scraper.md - **Developed by:** [The Mine Works](https://apify.com/themineworks) (community) - **Categories:** Marketing, Developer tools, MCP servers - **Stats:** 3 total users, 2 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $3.00 / 1,000 ad scrapeds 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 Ad Library Scraper — Ads, Images & Videos Pull live ads from the **Meta (Facebook & Instagram) Ad Library** by keyword or advertiser. For every ad you get the creative copy, the image and video URLs, the advertiser, the platforms it runs on, and the run dates. Optionally the actor downloads the image and video creatives straight into your dataset so you can study competitor creative at scale. No login, no API key, no third-party unblocker. **Works in Claude, ChatGPT & any MCP-compatible AI agent.** Built for competitive ad research, creative inspiration, brand monitoring, and ad-intelligence pipelines. ### What you get per ad | Field | Description | |-------|-------------| | `ad_archive_id` | The Ad Library ID for the ad | | `page_name`, `page_id` | The advertiser | | `ad_body` | The primary ad text | | `ad_title`, `ad_caption` | Headline and caption | | `cta_text`, `cta_type` | Call to action (e.g. Shop Now) | | `link_url` | The destination the ad points to | | `image_urls` | Every image creative URL in the ad | | `video_urls` | Every video creative URL in the ad | | `downloaded_images` | Direct download links to the saved images (if enabled) | | `downloaded_videos` | Direct download links to the saved videos (if enabled) | | `publisher_platforms` | facebook, instagram, audience_network, messenger | | `is_active`, `start_date`, `end_date`, `total_active_days` | Run status and timing | | `display_format` | image, video, carousel, dco | | `snapshot_url` | Open the ad directly in the Ad Library | ### Input | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `searchTerms` | array | one of these | — | Keywords to search, e.g. a brand or product name | | `pageIds` | array | one of these | — | Advertiser Page IDs to pull ALL of an advertiser's ads (precise competitor tracking) | | `country` | string | no | `US` | Two-letter country code (the Ad Library is country-scoped), e.g. US, IN, GB, AE | | `adActiveStatus` | select | no | `active` | active / inactive / all | | `adType` | select | no | `all` | All ads, or political and issue ads (which carry spend and impression data) | | `mediaType` | select | no | `all` | all / image / video / meme | | `maxAdsPerSearch` | integer | no | `50` | Cap per term or advertiser (1 to 2000) | | `downloadImages` | boolean | no | `true` | Save image creatives to the key-value store | | `downloadVideos` | boolean | no | `false` | Save video creatives too (large, slower) | | `proxyConfiguration` | object | no | RESIDENTIAL | Residential proxy is required | #### Finding an advertiser Page ID Open any of a brand's ads in the Ad Library. The detail panel shows the Page. The numeric `view_all_page_id` in the URL is the Page ID you pass to `pageIds`. Searching by Page ID is the most reliable way to track a single competitor over time. ### How it works The public Ad Library renders its results from an internal GraphQL endpoint. This actor drives a real Chromium browser through an Apify **residential** proxy, opens the country-scoped search, and reads the ad data out of the GraphQL responses as it scrolls. Because the ad objects are extracted recursively, the actor keeps working even when Meta reshuffles the exact response shape. Image and video creatives are then fetched through the same proxy and written to the run's key-value store, with a direct link returned on each record. Residential proxies are required (pre-filled). The actor never fails on zero results and never charges for an ad it could not deliver. ### Pricing First **25 ads free** per Apify account (lifetime). After that, **$0.003 per ad** delivered, creatives included. Ads that fail to load are never charged. ### Related Actors | Actor | Use case | |-------|----------| | [Instagram Profile Scraper](https://apify.com/themineworks/instagram-profile-scraper) | Profile data for the advertisers you find | | [Google Trends Scraper Pro](https://apify.com/themineworks/google-trends-pro) | Validate demand for the products being advertised | | [Trustpilot Scraper](https://apify.com/themineworks/trustpilot-reviews) | Reputation of the brands running the ads | # Actor input Schema ## `searchTerms` (type: `array`): Keywords to search the Ad Library for, e.g. a brand or product name. Each term is searched independently. Leave empty if you are searching by advertiser Page ID instead. ## `pageIds` (type: `array`): Facebook Page IDs to pull ALL ads from a specific advertiser. Find a Page ID inside any ad's Ad Library detail. Use this for precise competitor tracking. Takes priority over search terms. ## `country` (type: `string`): Two-letter country code for the Ad Library region, e.g. US, IN, GB, AE. The Ad Library is country-scoped. ## `adActiveStatus` (type: `string`): Which ads to return. ## `adType` (type: `string`): All commercial ads, or only political and issue ads (which carry extra spend and impression data). ## `mediaType` (type: `string`): Filter ads by creative type. ## `maxAdsPerSearch` (type: `integer`): Maximum number of ads to collect for each search term or advertiser. ## `downloadImages` (type: `boolean`): Save each ad's image creatives to this run's key-value store and return a direct download link per image. Turn off to return image URLs only. ## `downloadVideos` (type: `boolean`): Save each ad's video creatives to the key-value store too. Videos are large and slower; off by default. Video URLs are always returned regardless. ## `proxyConfiguration` (type: `object`): Residential proxy is required — Meta rate-limits and fingerprints the Ad Library by IP. Leave as default. ## Actor input object example ```json { "searchTerms": [ "lab grown diamonds" ], "country": "US", "adActiveStatus": "active", "adType": "all", "mediaType": "all", "maxAdsPerSearch": 50, "downloadImages": true, "downloadVideos": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ```` # 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 = { "searchTerms": [ "lab grown diamonds" ], "country": "US", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("themineworks/meta-ad-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchTerms": ["lab grown diamonds"], "country": "US", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("themineworks/meta-ad-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchTerms": [ "lab grown diamonds" ], "country": "US", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call themineworks/meta-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=themineworks/meta-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper — Facebook & Instagram Ads ✅ No Login", "description": "Scrape live ads from the Meta (Facebook & Instagram) Ad Library by keyword or advertiser. Get ad copy, image and video URLs, advertiser, platforms and run dates, and optionally download the creatives. No login. Works in Claude, ChatGPT & any MCP-compatible AI agent.", "version": "0.1", "x-build-id": "ZdIOfFgKGmthuo6jS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/themineworks~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-themineworks-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/themineworks~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-themineworks-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/themineworks~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-themineworks-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchTerms": { "title": "Search terms (keywords)", "type": "array", "description": "Keywords to search the Ad Library for, e.g. a brand or product name. Each term is searched independently. Leave empty if you are searching by advertiser Page ID instead.", "items": { "type": "string" } }, "pageIds": { "title": "Advertiser Page IDs (optional)", "type": "array", "description": "Facebook Page IDs to pull ALL ads from a specific advertiser. Find a Page ID inside any ad's Ad Library detail. Use this for precise competitor tracking. Takes priority over search terms.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for the Ad Library region, e.g. US, IN, GB, AE. The Ad Library is country-scoped.", "default": "US" }, "adActiveStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Which ads to return.", "default": "active" }, "adType": { "title": "Ad type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "All commercial ads, or only political and issue ads (which carry extra spend and impression data).", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Filter ads by creative type.", "default": "all" }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Maximum number of ads to collect for each search term or advertiser.", "default": 50 }, "downloadImages": { "title": "Download image creatives", "type": "boolean", "description": "Save each ad's image creatives to this run's key-value store and return a direct download link per image. Turn off to return image URLs only.", "default": true }, "downloadVideos": { "title": "Download video creatives", "type": "boolean", "description": "Save each ad's video creatives to the key-value store too. Videos are large and slower; off by default. Video URLs are always returned regardless.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Residential proxy is required — Meta rate-limits and fingerprints the Ad Library by IP. Leave as default." } } }, "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 } } } } } } } } } } ```