# Meta Ad Library Scraper (`ivanvs/meta-ad-library-scraper`) Actor Extract details about ads from Meta Ad Library. Scrape ad details like when it was run, ad platfor, advertiser and content of ad. Download ad data in JSON, XML, Excel format. - **URL**: https://apify.com/ivanvs/meta-ad-library-scraper.md - **Developed by:** [Gen First](https://apify.com/ivanvs) (community) - **Categories:** Social media, Lead generation, E-commerce - **Stats:** 28 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.90 / 1,000 ad informations 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 Scraper Scrape listings from [Meta Ad Library](https://www.facebook.com/ads/library) easily with Meta Ad Library Scraper. ### About #### Meta Platforms Meta Platforms, Inc. (formerly Facebook, Inc.) is an American multinational technology company headquartered in Menlo Park, California. Founded by Mark Zuckerberg and his Harvard roommates in February 2004 as "TheFacebook", it was renamed Facebook in 2005 and rebranded to Meta in October 2021 to signal a broader ambition beyond social networking — toward the so-called metaverse. Meta is one of the "Big Five" American tech companies alongside Alphabet, Amazon, Apple, and Microsoft. Its family of apps — Facebook, Instagram, WhatsApp, and Messenger — collectively reach over **3.2 billion daily active users** worldwide, making it the largest social media ecosystem on the planet. Facebook alone counts roughly **3 billion monthly active users**. Meta has grown aggressively through acquisitions. Key milestones: - **2005** — purchased the facebook.com domain for $200,000 - **2010** — acquired social gaming companies Hot Potato and photo sharing app Nextstop - **2012** — bought **Instagram** for ~$1 billion (cash and stock), at the time one of the largest tech acquisitions ever for an app with no revenue - **2013** — acquired **Parse**, a mobile backend platform, for ~$85 million (later shut down in 2017) - **2014** — purchased **WhatsApp** for ~$19 billion, making it the largest acquisition of a venture-backed company in history at the time; also acquired **Oculus VR** for ~$2 billion, signaling early interest in virtual reality - **2016** — bought **MSQRD** (augmented reality face filters) and **Masquerade**, key building blocks for Facebook and Instagram AR effects - **2019** — acquired **CTRL-labs**, a startup working on neural interface technology, for a reported $500 million–$1 billion - **2020** — purchased **Mapillary**, a street-level imagery platform, to power mapping for AR features - **2021** — rebranded to **Meta Platforms** and doubled down on the metaverse; acquired several VR/AR studios including **Unit 2 Games** (Crayta) and **BigBox VR** - **2022** — attempted to acquire **Within** (VR fitness app maker), ultimately blocked by the FTC on antitrust grounds in 2023 Meta's acquisition strategy has consistently focused on eliminating potential social competitors early (Instagram, WhatsApp) and acquiring enabling technology for its next strategic bets (VR/AR, neural interfaces). Advertising is the core of Meta's business model, accounting for around **97% of its total revenue**. The company's ad targeting capabilities — built on vast behavioral and demographic data — make it one of the most powerful digital advertising platforms in the world, alongside Google. #### Meta Ad Library The Meta Ad Library is a publicly accessible, searchable repository of all ads currently running across Meta's platforms — Facebook, Instagram, Messenger, and Audience Network. It was launched in **2018** as a transparency measure following widespread criticism over the role of political advertising and disinformation in the 2016 US presidential election. Initially covering only political and social issue ads in the United States, the library expanded in **2019** to include all active ads globally. For political and social issue ads, records are retained for **7 years** after a campaign ends; for all other ads, data is kept for at least **1 year**. The library is freely accessible at `https://www.facebook.com/ads/library` and requires no login. It provides advertisers' names, the pages running the ads, creative content, estimated reach, spend ranges, and — for political ads — payer and beneficiary disclosures. Under the EU **Digital Services Act (DSA)**, Meta is additionally required to publish a machine-readable ad repository covering EU-targeted advertising, including audience targeting parameters and impression counts. This makes the Ad Library a key resource for researchers, journalists, and regulators monitoring advertising transparency and potential disinformation campaigns. ### Why should you use it? It provides the latest ads data from Meta Ad Library, without requiring login or session cookies. ### How to use Meta Ad Library Scraper has number of input parameters that can be used. | Input parameter | Description | Required | Default value | | --------------- | --------------------------------------------- | -------- | -------------------------------------------------------------------- | | urls | Meta Ad Library urls that needs to be scraped | `true` | `{url: "https://www.facebook.com/ads/library/?id=1873455736760336"}` | | maxRecords | Maximum number of records to be scraped | `false` | 100 | Valid Meta Ad Library links: - https://www.facebook.com/ads/library/?id=1873455736760336 - https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc ### Examples #### Input Scrape 20 search results from given search URL: ```json { "urls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc" ], "maxRecords": 20 } ```` #### Output The output below is a synthetic example showing all fields in a fully populated state. ```json { "adId": "123456789012345", "pageId": "987654321098765", "pageName": "Acme Corp", "pageIsDeleted": false, "collationId": "111222333444555", "collationCount": 5, "isActive": true, "hasUserReported": false, "reportCount": 2, "stateMediaRunLabel": "ACTIVE", "gatedType": "ELIGIBLE", "categories": ["HOUSING"], "isAaaEligible": true, "containsDigitalCreatedMedia": false, "accountsReached": 45000, "currency": "USD", "adSpend": "1000-1999", "endDate": 1798761600, "endDateUtc": "2027-01-01T00:00:00.000Z", "startDate": 1735689600, "startDateUtc": "2025-01-01T00:00:00.000Z", "publisherPlatform": ["FACEBOOK", "INSTAGRAM"], "containsSensitiveContent": false, "totalActiveTime": 365, "hideDataStatus": "NONE", "impressionsText": "1M–2M", "targetedOrReachedCountries": ["US", "CA"], "regionalRegulationData": { "finserv": { "isDeemedFinserv": true, "isLimitedDelivery": false }, "twAntiScam": { "isLimitedDelivery": false } }, "adContent": { "caption": "acmecorp.com", "ctaText": "Shop Now", "ctaType": "SHOP_NOW", "displayFormat": "VIDEO", "linkUrl": "https://www.acmecorp.com/sale?utm_source=facebook", "linkDescription": "Save up to 50% on all products this week only.", "body": "Discover our latest collection. Quality products at unbeatable prices.", "title": "Acme Corp — End of Season Sale", "byline": "Sponsored", "isReshared": false, "images": [ { "originalImageUrl": "https://example.cdn.net/images/acme_banner_original.jpg", "resizedImageUrl": "https://example.cdn.net/images/acme_banner_600x600.jpg" } ], "videos": [ { "videoSdUrl": "https://example.cdn.net/videos/acme_promo_sd.mp4", "videoHdUrl": "https://example.cdn.net/videos/acme_promo_hd.mp4", "thumbnailUrl": "https://example.cdn.net/images/acme_promo_thumb.jpg" } ], "cards": [ { "caption": "acmecorp.com", "title": "Product A", "body": "Best deal of the year", "linkUrl": "https://www.acmecorp.com/product-a", "ctaText": "Buy Now", "images": [ { "originalImageUrl": "https://example.cdn.net/images/product_a_original.jpg", "resizedImageUrl": "https://example.cdn.net/images/product_a_600x600.jpg" } ] } ] }, "advertiser": { "id": "987654321098765", "name": "Acme Corp", "alias": "acmecorp", "category": "Retail Company", "profileUri": "https://facebook.com/acmecorp", "profilePhoto": "https://example.cdn.net/images/acme_profile.jpg", "coverPhoto": "https://example.cdn.net/images/acme_cover.jpg", "entityType": "BRAND", "likes": 128400, "verification": "BLUE_VERIFIED", "isDeleted": false, "isRestricted": false, "isProfilePage": false, "igFollowers": 85200, "igUsername": "acmecorp_official", "igVerification": "BLUE_VERIFIED", "about": "Acme Corp is a global retailer of quality everyday products.", "spend": { "isPoliticalPage": false, "currentWeek": "500-999", "lifetimeByDisclaimer": [{ "disclaimer": "Acme Corp", "spend": "100000-499999" }], "weeklyByDisclaimer": [{ "disclaimer": "Acme Corp", "spend": "500-999" }] } }, "aaaInfo": { "payerBeneficiaryData": [{ "payer": "Acme Corp", "beneficiary": "Acme Corp" }], "targetsEu": true, "hasViolatingPayerBeneficiary": false, "isAdTakenDown": false }, "violationTypes": ["POLICY_VIOLATION"], "transparencyByLocation": { "euTransparency": { "targetsEu": true, "locationAudience": [ { "name": "Germany", "numObfuscated": 0, "type": "countries", "excluded": false }, { "name": "France", "numObfuscated": 0, "type": "countries", "excluded": false } ], "genderAudience": "All", "ageAudience": { "min": 18, "max": 65 }, "euTotalReach": 34200, "ageCountryGenderReachBreakdown": [ { "country": "DE", "ageGenderBreakdowns": [ { "ageRange": "18-24", "male": 4200, "female": 3800, "unknown": 120 }, { "ageRange": "25-34", "male": 8100, "female": 6500, "unknown": 210 } ] } ] }, "brTransparency": null, "ukTransparency": null }, "isViolatingEuSiep": false, "url": "https://www.facebook.com/ads/library/?id=123456789012345" } ``` ### Meta Ad Library Scraper data output The output from Meta Ad Library Scraper is stored in the dataset. After the run is finished, you can download the dataset in various data formats (JSON, CSV, XML, RSS, HTML Table). ### ❓FAQ #### Do I need proxies to scrape ads from Meta Ad Library? Proxy for this scraper is already preconfigured for optimal performance. ### Support For more custom/simplify outputs or Bug report please contact the developer (support (at) getmediumdata.com) or report an issue. # Actor input Schema ## `maxRecords` (type: `integer`): Maximum number of records to be scraped ## `urls` (type: `array`): List of URLs from Meta Ad Library (https://www.facebook.com/ads/library) that needs to be scraped ## Actor input object example ```json { "maxRecords": 10, "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc" } ] } ``` # 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 = { "maxRecords": 10, "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("ivanvs/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 = { "maxRecords": 10, "urls": [{ "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc" }], } # Run the Actor and wait for it to finish run = client.actor("ivanvs/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 '{ "maxRecords": 10, "urls": [ { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&q=jetbrains&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc" } ] }' | apify call ivanvs/meta-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ivanvs/meta-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper", "description": "Extract details about ads from Meta Ad Library. Scrape ad details like when it was run, ad platfor, advertiser and content of ad. Download ad data in JSON, XML, Excel format.", "version": "0.0", "x-build-id": "7CBmN9z2W4FFXicZc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ivanvs~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ivanvs-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/ivanvs~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-ivanvs-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/ivanvs~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-ivanvs-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", "required": [ "urls" ], "properties": { "maxRecords": { "title": "Maximum number of records", "minimum": 1, "type": "integer", "description": "Maximum number of records to be scraped", "default": 100 }, "urls": { "title": "List of URLs", "type": "array", "description": "List of URLs from Meta Ad Library (https://www.facebook.com/ads/library) that needs to be scraped", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } } } }, "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 } } } } } } } } } } ```