# Meta Ads Library Scraper (`solidcode/meta-ads-library-scraper`) Actor \[💰 $0.4 / 1K] Extract ads from Meta's public Ad Library across Facebook, Instagram, Messenger, Audience Network, Threads, and WhatsApp. Search by keyword, advertiser page, or Ad Library URL. Returns ad copy, CTAs, advertiser details, dates, platforms, and audience estimates. No login required. - **URL**: https://apify.com/solidcode/meta-ads-library-scraper.md - **Developed by:** [SolidCode](https://apify.com/solidcode) (community) - **Categories:** Social media, Lead generation, Automation - **Stats:** 8 total users, 4 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.40 / 1,000 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 — Facebook Ads Scraper (Facebook, Instagram & Messenger Ads) The Meta Ads Library Scraper is a Facebook Ads Scraper for the public Meta Ad Library. Scrape Facebook ads, Instagram ads, Messenger ads, and Audience Network ads at scale — search by keyword, advertiser page URL, or any Ad Library URL, and receive structured JSON with ad copy, CTAs, advertiser data, start/end dates, and per-platform breakdowns. Built for marketers, researchers, and competitive-intelligence teams who need fresh Facebook ad data without spending hours clicking through the Ad Library UI. ### Why This Meta Ads Library Scraper? - **Live data straight from the public Meta Ad Library** — every run reflects what's currently published on Facebook and Instagram, not a stale cache - **Six Meta ad surfaces in one schema** — Facebook ads, Instagram ads, Messenger ads, Audience Network, Threads, and WhatsApp ads unified under a single `publisherPlatforms` field - **52 supported countries** plus an "All countries" mode — scrape Facebook ads from every market in one job, no per-country runs - **Keyword search, advertiser page URL, or pasted Ad Library URL** — mix all three in one run; URL filters (active status, media type, language, date range) are preserved automatically - **Political-ad transparency fields included** — estimated audience size, declared spend ranges, demographic reach, and regional breakdowns for political/issue, housing, employment, and credit ads - **Pay only for the depth you need** — base ad data, optional creative details (CTA link, headline, snapshot URL), and optional advertiser-page enrichment (category, like count, verified flag, linked Instagram handle, follower count) are billed as separate events - **Pre-flight count mode** — return only the total matching-ad count per source, billed as a single low-cost summary row, before committing to a full Facebook ads scrape - **No Facebook login required** — the Ad Library is a public transparency database; this scraper does not need credentials, cookies, or any account access - **Structured JSON output** — camelCase fields, ISO 8601 dates, and ready for Zapier, Make, Google Sheets, or your own pipeline ### Supported Platforms - Facebook - Instagram - Messenger - Audience Network - Threads - WhatsApp ### Use Cases **Competitor Research & Ad Spy** - Track every Facebook ad a rival brand has ever run — active or stopped — to map their creative strategy and messaging evolution - Compare Instagram ads side-by-side across competing e-commerce brands to identify winning offers and seasonal campaigns - Monitor a competitor's Facebook ad volume over time using the pre-flight count mode as a pulse check - Build a Facebook ad library of competitor creative for swipe files, agency pitches, and creative reviews **Ad Creative Analysis** - Aggregate ad copy from hundreds of Facebook advertisers in a category to spot copy patterns and angle trends - Filter Facebook and Instagram ads by media type (image vs. video) to benchmark creative mix across a vertical - Export CTAs and headlines in bulk for copywriting research and A/B inspiration **Political-Ad Transparency & Compliance** - Pull every political or social-issue ad running in a given country to audit declared spend ranges and audience estimates - Research election-period Facebook ad activity for journalism, academic study, or regulatory compliance - Filter by the "Political & social-issue ads" category to access Meta's mandatory disclosures: estimated audience size, regional reach, and demographic breakdowns **E-commerce & DTC Intelligence** - Scrape Instagram ads from direct-to-consumer brands to monitor product launches, discount offers, and creative fatigue signals - Build a dataset of active Facebook ads by category to inform media-buying decisions or benchmark CPM-proxy signals - Track when a competitor goes dark (no active ads) or ramps up spend intensity **Influencer & Affiliate Research** - Find all ads from a specific advertiser page to identify which affiliate offers are actively running - Filter by platform to see which brands are investing in Instagram versus Facebook versus Messenger - Pull ad copy for compliance review or brand-safety screening **Brand Safety & Monitoring** - Monitor whether your brand name appears in competitor ads using keyword search - Track impersonator pages by searching your brand terms and checking advertiser page IDs against your verified list - Alert on new ads from a specific page URL to catch unauthorized use of your brand identity ### Getting Started #### Search Facebook Ads by Keyword (simplest) Search Facebook and Instagram ads by topic or brand name across all countries: ```json { "searchTerms": ["nike"], "maxResults": 100 } ```` #### Keyword Search with Filters Search for active Facebook and Instagram video ads in the United States published after a specific date: ```json { "searchTerms": ["electric scooter", "e-scooter"], "country": "US", "adActiveStatus": "ACTIVE", "mediaType": "VIDEO", "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"], "dateFrom": "2025-01-01", "maxResults": 500 } ``` #### Scrape All Facebook Ads from a Specific Advertiser Pass a Facebook page URL to collect every public Facebook ad run by that advertiser: ```json { "pageUrls": ["https://www.facebook.com/nike"], "country": "US", "adActiveStatus": "ALL", "scrapeAdDetails": true, "includeAboutPage": true, "maxResults": 1000 } ``` #### Paste a Facebook Ad Library URL Copy any URL from the Facebook Ad Library UI — all filters encoded in the URL are preserved automatically: ```json { "startUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=running+shoes&media_type=image" ], "maxResults": 200 } ``` #### Political Ads with Full Transparency Data Pull political and issue ads for a country to access spend ranges, audience estimates, and demographic breakdowns: ```json { "searchTerms": ["vote", "election"], "country": "US", "adType": "POLITICAL_AND_ISSUE_ADS", "scrapeAdDetails": true, "maxResults": 500 } ``` #### Pre-flight Count Check Check how many matching Facebook ads exist before running the full scrape: ```json { "searchTerms": ["crypto trading"], "country": "ALL", "onlyTotalCount": true } ``` ### Input Reference #### What to Scrape | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `searchTerms` | string\[] | `["nike"]` | Keywords to search the Ad Library for (e.g. `"electric scooter"`, `"crypto trading"`). Each term runs as its own Ad Library search. Leave empty if you only want to use Page URLs or Ad Library URLs. | | `pageUrls` | string\[] | `[]` | Facebook page URLs (e.g. `https://www.facebook.com/nike`) or numeric page IDs. Returns every public ad currently or historically run by that advertiser. | | `startUrls` | string\[] | `[]` | Paste full Meta Ad Library URLs (`https://www.facebook.com/ads/library/?...`) — every filter encoded in the URL is preserved. Useful when you've already configured a search in the Ad Library UI. | #### Filters All filters apply to Search Terms and Advertiser Pages. Filters are ignored on URLs you paste into "Ad Library URLs" — those URLs already carry their own filters. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `country` | string | `"ALL"` | Country whose Ad Library to query. Use `"ALL"` to search every country at once. Applied to Search Terms and Advertiser Pages; URLs in "Ad Library URLs" use whatever country is encoded in the URL. | | `adActiveStatus` | string | `"ALL"` | Whether to return only currently-running ads (`"ACTIVE"`), only stopped/inactive ads (`"INACTIVE"`), or both (`"ALL"`). The Ad Library marks ads ACTIVE while they're still being delivered and INACTIVE once they've stopped. | | `adType` | string | `"ALL"` | Meta groups ads into transparency categories. `"ALL"` covers every public ad. The other categories surface political/issue, housing, employment, and credit ads where Meta provides additional disclosures (audience estimates, sometimes spend). Options: `"ALL"`, `"POLITICAL_AND_ISSUE_ADS"`, `"HOUSING_ADS"`, `"EMPLOYMENT_ADS"`, `"CREDIT_ADS"`. | | `mediaType` | string | `"ALL"` | Restrict results by creative format. Options: `"ALL"`, `"IMAGE"`, `"VIDEO"`, `"MEME"`, `"NONE"` (text only). | | `publisherPlatforms` | string\[] | `[]` | Only include ads that ran on these Meta surfaces. Leave empty to include every platform. Options: `"FACEBOOK"`, `"INSTAGRAM"`, `"MESSENGER"`, `"AUDIENCE_NETWORK"`, `"THREADS"`, `"WHATSAPP"`. | | `languages` | string\[] | `[]` | Only include ads whose creative is in one of these languages. Leave empty for any language. Options: English, Spanish, Portuguese, French, German, Italian, Dutch, Polish, Turkish, Russian, Arabic, Hebrew, Japanese, Korean, Chinese, Hindi, Indonesian, Thai, Vietnamese. | | `dateFrom` | string | `""` | Only include ads that first ran on or after this date (`YYYY-MM-DD`). Leave empty for no lower bound. | | `dateTo` | string | `""` | Only include ads that first ran on or before this date (`YYYY-MM-DD`). Leave empty for no upper bound. | #### Enrichment Each enrichment toggle adds an extra per-row charge on top of the base ad price — see Pricing below for the rates. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `scrapeAdDetails` | boolean | `false` | Attach creative-level details to every ad row (CTA link, headline, card description, snapshot URL, and CTA button label). Each row that gets these fields is billed at the **Creative details** rate. Disabled when "Only return total count" is on. | | `includeAboutPage` | boolean | `false` | Look up each advertiser's Facebook page and attach extra fields (category, like count, verified flag, linked Instagram handle, follower count). Each enriched row is billed at the **Advertiser details** rate. Disabled when "Only return total count" is on. | | `onlyTotalCount` | boolean | `false` | Pre-flight mode — return one row per source containing only the total matching-ad count. Useful for sizing a job before committing budget. Each summary row is billed at the **Total count** rate (much cheaper than full ad collection). When enabled, ad rows are not produced and enrichment toggles are ignored. | #### Limits | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `maxResults` | integer | `100` | Cap on total ads collected across every source. Set to `0` for unlimited (the run will keep paginating until Meta returns no more results). Each row is billed at the per-result rate. | ### Output Each ad row contains the fields below. A realistic example with all enrichment enabled: ```json { "adArchiveID": "1234567890123456", "adLibraryURL": "https://www.facebook.com/ads/library/?id=1234567890123456", "pageID": "15087023", "pageName": "Nike", "adStatus": "ACTIVE", "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"], "startDate": "2025-03-15", "endDate": null, "adCreationTime": "2025-03-14T18:30:00+00:00", "adText": "Run your world. New Air Max 2025 — designed for everyday miles.", "adCreativeBodies": [ "Run your world. New Air Max 2025 — designed for everyday miles." ], "ctaDomain": "nike.com", "ctaUrl": "https://www.nike.com/air-max", "ctaHeadline": "Air Max 2025", "ctaDescription": "Shop the latest Air Max collection.", "ctaText": "Shop Now", "ctaType": "SHOP_NOW", "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=1234567890123456", "pageURL": "https://www.facebook.com/nike", "pageProfilePictureURL": "https://example.com/nike-profile.jpg", "pageCategory": "Sportswear Store", "pageLikes": 35100000, "pageVerified": true, "pageInstagramUser": "nike", "pageInstagramFollowers": 302000000, "pageCountry": null, "pageAboutText": "Just Do It.", "spend": null, "impressions": null, "reachEstimate": null, "currency": null, "estimatedAudienceSize": null, "regionsReached": null, "demographics": null, "source": "search", "sourceQuery": "nike" } ``` #### All Available Fields | Field | Type | Description | |-------|------|-------------| | `adArchiveID` | string | Meta's permanent ad archive ID | | `adLibraryURL` | string | Direct link to this ad in the public Meta Ad Library | | `pageID` | string | Facebook page ID of the advertiser | | `pageName` | string | Advertiser's Facebook page display name | | `adStatus` | string | `"ACTIVE"` while the ad is being delivered; `"INACTIVE"` once stopped | | `publisherPlatforms` | string\[] | Surfaces where this ad ran — `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `AUDIENCE_NETWORK`, `THREADS`, `WHATSAPP` | | `startDate` | string | ISO date the ad first started running | | `endDate` | string | ISO date the ad stopped (null if still active) | | `adCreationTime` | string | ISO 8601 timestamp of ad creation | | `adText` | string | Primary body copy of the ad creative | | `adCreativeBodies` | string\[] | All body copy variants (Meta sometimes returns per-placement variants) | | `ctaDomain` | string | Landing-page domain shown on the ad card (`scrapeAdDetails` required) | | `ctaUrl` | string | Full destination URL of the CTA button (`scrapeAdDetails` required) | | `ctaHeadline` | string | Card headline (`scrapeAdDetails` required) | | `ctaDescription` | string | Card link description (`scrapeAdDetails` required) | | `ctaText` | string | CTA button label, e.g. "Shop Now" (`scrapeAdDetails` required) | | `ctaType` | string | CTA button type enum, e.g. `SHOP_NOW` (`scrapeAdDetails` required) | | `adSnapshotUrl` | string | Direct iframe render URL for the ad creative — `https://www.facebook.com/ads/archive/render_ad/?id=...` (`scrapeAdDetails` required) | | `pageURL` | string | Public Facebook page URL (`scrapeAdDetails` or `includeAboutPage` required) | | `pageProfilePictureURL` | string | Advertiser's profile picture URL (`scrapeAdDetails` required) | | `pageCategory` | string | Meta-assigned page category, e.g. "Sportswear Store" (`includeAboutPage` required) | | `pageLikes` | integer | Facebook page like count (`includeAboutPage` required) | | `pageVerified` | boolean | `true` if the page holds a blue verified badge (`includeAboutPage` required) | | `pageInstagramUser` | string | Linked Instagram username (`includeAboutPage` required) | | `pageInstagramFollowers` | integer | Instagram follower count for the linked account (`includeAboutPage` required) | | `pageCountry` | string | Advertiser's declared country (null — Meta no longer exposes this field) | | `pageAboutText` | string | Advertiser's "About" bio text (`includeAboutPage` required) | | `spend` | object | Declared spend range — only populated for political/housing/employment/credit ads | | `impressions` | object | Impression range — only for special-category ads | | `reachEstimate` | object | Estimated reach — only for special-category ads | | `currency` | string | Currency code for spend — only for special-category ads | | `estimatedAudienceSize` | object | `{ lower_bound, upper_bound }` — only for special-category ads | | `regionsReached` | object | Per-region geographic breakdown — only for special-category ads | | `demographics` | object\[] | Age/gender reach breakdown — only for special-category ads | | `source` | string | Which input produced this row: `"search"`, `"page"`, or `"url"` | | `sourceQuery` | string | The originating search term, page URL, or Ad Library URL | ### Tips for Best Results - **Size the job first with `onlyTotalCount: true`** — each summary row is billed at the cheap Total count rate, so you can confirm a query has the Facebook ad volume you expect before committing budget - **Use "Ad Library URL" input** when you need complex filter combinations (e.g. specific audiences, custom country sets) — configure your search in the Facebook Ad Library UI first, then copy the URL - **Only enable enrichment when you need it** — `scrapeAdDetails` and `includeAboutPage` each add a per-row surcharge on top of the base ad price; leave them off for ad-copy-only research - **Use `adType: "POLITICAL_AND_ISSUE_ADS"`** when researching election or advocacy campaigns — this unlocks Meta's mandatory transparency disclosures (estimated audience, spend ranges, regional reach) - **Filter by `publisherPlatforms`** to isolate Instagram-only ads or Facebook-only ads when benchmarking platform-specific creative strategies - **Set `maxResults: 0`** only for small advertisers or narrow queries — for broad keyword searches Meta can return tens of thousands of Facebook ads - **Use date filters** (`dateFrom` / `dateTo`) to scope your scrape to a campaign window and avoid processing historical ads you don't need ### Pricing This Facebook ads scraper uses Apify's **Pay-per-event** model — among the lowest prices on Apify for Meta Ad Library data. You only pay for the data you collect, and enrichment toggles are billed as separate events so a basic run stays cheap. | Event | Fires when | Rate | |-------|------------|------| | **Ad result** | Every ad row pushed to the dataset | $0.40 / 1,000 ads | | **Creative details** | Per ad row when `scrapeAdDetails` is on (adds CTA link, headline, card description, snapshot URL, CTA button label) | $0.10 / 1,000 ads | | **Advertiser page details** | Per ad row when `includeAboutPage` is on (adds page category, like count, verified flag, Instagram username + follower count, About text) | $0.40 / 1,000 ads | | **Pre-flight count** | Per summary row in `onlyTotalCount` mode (one row per source) | $0.02 each | #### Example costs | Configuration | 100 ads | 1,000 ads | 10,000 ads | 100,000 ads | |---------------|---------|-----------|------------|-------------| | Base only (no enrichment) | $0.04 | $0.40 | $4.00 | $40.00 | | Base + creative details | $0.05 | $0.50 | $5.00 | $50.00 | | Base + advertiser details | $0.08 | $0.80 | $8.00 | $80.00 | | Base + both enrichments (full) | $0.09 | $0.90 | $9.00 | $90.00 | `onlyTotalCount` runs are billed at $0.02 per source — a 100-keyword pre-flight check costs $2.00. No compute charges and no hidden fees — the per-event price is everything you pay. ### Integrations Export data in JSON, CSV, Excel, XML, or RSS. Connect to 1,500+ apps via: - **Zapier** / **Make** / **n8n** — Workflow automation — trigger a Slack alert when a competitor runs a new Facebook ad - **Google Sheets** — Export directly to a spreadsheet for collaborative analysis - **Webhooks** — POST results to your own endpoint the moment a run completes - **Apify API** — Full programmatic access; schedule runs, read datasets, and chain actors - **Apify CLI** — Trigger runs and download results from the command line ### Frequently Asked Questions **How do I scrape Facebook ads?** Use the `searchTerms` input to search Facebook ads by keyword, or paste a Facebook page URL into `pageUrls` to pull every ad from a specific advertiser. Both methods query the public Meta Ad Library — no Facebook account, login, or cookies required. **What is the best Facebook ads scraper on Apify?** This actor is purpose-built for the Meta Ad Library and consistently among the lowest-priced Facebook ads scrapers on the platform: $0.40 per 1,000 ads with no compute charges, optional creative-detail and advertiser-page enrichment billed as separate events, and a pre-flight count mode so you can size jobs before paying. **Can I download Instagram ads from the Meta Ad Library?** Yes. The Meta Ad Library includes all Instagram ads that advertisers have run across Meta's platforms. Set `publisherPlatforms: ["INSTAGRAM"]` to filter for Instagram-only ads, or leave it empty to include ads from all surfaces (Facebook, Instagram, Messenger, Audience Network, Threads, WhatsApp). **What data does the Meta Ad Library expose?** The public Meta Ad Library provides ad copy (body text), advertiser page name and ID, active/inactive status, platforms where the ad ran, start and end dates, and — for political, housing, employment, and credit ads — estimated audience sizes, spend ranges, regional reach, and demographic breakdowns. Enable `scrapeAdDetails` to also retrieve CTA links, headlines, card descriptions, and snapshot URLs. Enable `includeAboutPage` for page category, like count, and verified status. **Is scraping Facebook ads legal?** The Meta Ad Library is a public transparency database that Meta is legally required to maintain under EU and US regulations. Collecting data from it for research, journalism, competitive intelligence, and compliance purposes is widely accepted. Users are responsible for complying with applicable laws, Meta's Terms of Service, and any GDPR obligations when processing data about EU advertisers. **How do I find all ads from a specific advertiser?** Put the advertiser's Facebook page URL (e.g. `https://www.facebook.com/nike`) into the `pageUrls` field. The scraper will return every public ad that page has run — active and historical — up to your `maxResults` cap. You can also use a numeric Facebook page ID if you know it. **Why am I getting zero results?** The most common causes are: (1) the search term has no matching ads in the selected country — try `country: "ALL"` to search globally; (2) you've set `adActiveStatus: "ACTIVE"` and the advertiser has no currently-running campaigns; (3) the Ad Library uses the advertiser's page language, so try searching in the language the advertiser uses. The actor returns a status message with filter hints when zero results are found. **Can I scrape the Meta Ad Library without a Facebook account?** Yes — the Meta Ad Library is a public database with no login wall. This scraper does not require Facebook credentials, cookies, or any account access. **How do I scrape political ads and see spend data?** Set `adType: "POLITICAL_AND_ISSUE_ADS"`. Meta mandates additional transparency disclosures for these campaigns, including estimated audience size (`estimatedAudienceSize`), spend ranges (`spend`), impression ranges (`impressions`), and regional breakdowns (`regionsReached`). Commercial ads do not expose spend or reach data. ### Legal & Ethical Use This actor collects data from the Meta Ad Library, a public transparency resource that Meta is required to maintain under EU (Digital Services Act) and US political ad disclosure regulations. The data returned is intentionally public — Meta designed the Ad Library for exactly this kind of research. Users are responsible for: - Complying with Meta's Terms of Service and the Ad Library's usage policies - Observing applicable data protection laws (GDPR, CCPA) when processing EU or California resident data - Not using extracted data for spam, harassment, impersonation, or any other unlawful purpose This actor does not access private posts, personal profiles, or any data that Meta has not explicitly made public through the Ad Library. # Actor input Schema ## `searchTerms` (type: `array`): Keywords to search the Ad Library for (e.g. 'electric scooter', 'crypto trading'). Each term runs as its own Ad Library search. Leave empty if you only want to use Page URLs or Start URLs. ## `pageUrls` (type: `array`): Facebook page URLs (e.g. https://www.facebook.com/nike) or numeric page IDs. Returns every public ad currently or historically run by that advertiser. ## `startUrls` (type: `array`): Paste full Meta Ad Library URLs (https://www.facebook.com/ads/library/?...) — every filter encoded in the URL is preserved. Useful when you've already configured a search in the Ad Library UI. ## `country` (type: `string`): Country whose Ad Library to query. Use 'ALL' to search every country at once. Applied to Search Terms and Advertiser Pages; URLs in 'Ad Library URLs' use whatever country is encoded in the URL. ## `adActiveStatus` (type: `string`): Whether to return only currently-running ads, only stopped/inactive ads, or both. The Ad Library marks ads ACTIVE while they're still being delivered and INACTIVE once they've stopped. ## `adType` (type: `string`): Meta groups ads into transparency categories. 'All ads' covers every public ad. The other categories surface political/issue, housing, employment, and credit ads where Meta provides additional disclosures (audience estimates, sometimes spend). ## `mediaType` (type: `string`): Restrict results by creative format. ## `publisherPlatforms` (type: `array`): Only include ads that ran on these Meta surfaces. Leave empty to include every platform. ## `languages` (type: `array`): Only include ads whose creative is in one of these languages. Leave empty for any language. ## `dateFrom` (type: `string`): Only include ads that first ran on or after this date (YYYY-MM-DD). Leave empty for no lower bound. ## `dateTo` (type: `string`): Only include ads that first ran on or before this date (YYYY-MM-DD). Leave empty for no upper bound. ## `includeAboutPage` (type: `boolean`): Look up each advertiser's Facebook page and attach extra fields (category, like count, verified flag, linked Instagram handle, follower count). Each enriched row is billed at the additional 'Advertiser details' rate (see Pricing). Leave off unless you need the page metadata. Disabled when 'Only return total count' is on. ## `scrapeAdDetails` (type: `boolean`): Attach creative-level details to every ad row (CTA link, headline, card description, snapshot URL, and CTA button label). Each row that gets these fields is billed at the additional 'Creative details' rate (see Pricing). Disabled when 'Only return total count' is on. ## `onlyTotalCount` (type: `boolean`): Pre-flight mode — return one row per source containing only the total matching-ad count. Useful for sizing a job before committing budget. Each summary row is billed at the 'Total count' rate (much cheaper than full ad collection). Ad rows are not produced and enrichment toggles are ignored. ## `maxResults` (type: `integer`): Cap on total ads collected across every source. Set to 0 for unlimited (the run will keep paginating until Meta returns no more results). Each row is billed at the base 'Ad' rate (plus any enrichment surcharges). ## Actor input object example ```json { "searchTerms": [ "nike" ], "pageUrls": [], "startUrls": [], "country": "ALL", "adActiveStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "publisherPlatforms": [], "languages": [], "includeAboutPage": false, "scrapeAdDetails": false, "onlyTotalCount": false, "maxResults": 100 } ``` # Actor output Schema ## `overview` (type: `string`): Table of ads with key fields like advertiser, ad text, status, and dates. ## `details` (type: `string`): Full per-ad detail rows including advertiser-page enrichment, CTA details, and snapshot URL. # 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": [ "nike" ], "pageUrls": [], "startUrls": [], "country": "ALL", "adActiveStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "publisherPlatforms": [], "languages": [], "dateFrom": "", "dateTo": "", "includeAboutPage": false, "scrapeAdDetails": false, "onlyTotalCount": false, "maxResults": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("solidcode/meta-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 = { "searchTerms": ["nike"], "pageUrls": [], "startUrls": [], "country": "ALL", "adActiveStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "publisherPlatforms": [], "languages": [], "dateFrom": "", "dateTo": "", "includeAboutPage": False, "scrapeAdDetails": False, "onlyTotalCount": False, "maxResults": 100, } # Run the Actor and wait for it to finish run = client.actor("solidcode/meta-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 '{ "searchTerms": [ "nike" ], "pageUrls": [], "startUrls": [], "country": "ALL", "adActiveStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "publisherPlatforms": [], "languages": [], "dateFrom": "", "dateTo": "", "includeAboutPage": false, "scrapeAdDetails": false, "onlyTotalCount": false, "maxResults": 100 }' | apify call solidcode/meta-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=solidcode/meta-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ads Library Scraper", "description": "[💰 $0.4 / 1K] Extract ads from Meta's public Ad Library across Facebook, Instagram, Messenger, Audience Network, Threads, and WhatsApp. Search by keyword, advertiser page, or Ad Library URL. Returns ad copy, CTAs, advertiser details, dates, platforms, and audience estimates. No login required.", "version": "1.0", "x-build-id": "Yqr48DZgadaQDRONH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/solidcode~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-solidcode-meta-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/solidcode~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-solidcode-meta-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/solidcode~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-solidcode-meta-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": { "searchTerms": { "title": "Search Terms", "type": "array", "description": "Keywords to search the Ad Library for (e.g. 'electric scooter', 'crypto trading'). Each term runs as its own Ad Library search. Leave empty if you only want to use Page URLs or Start URLs.", "items": { "type": "string" } }, "pageUrls": { "title": "Advertiser Page URLs", "type": "array", "description": "Facebook page URLs (e.g. https://www.facebook.com/nike) or numeric page IDs. Returns every public ad currently or historically run by that advertiser.", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste full Meta Ad Library URLs (https://www.facebook.com/ads/library/?...) — every filter encoded in the URL is preserved. Useful when you've already configured a search in the Ad Library UI.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "US", "CA", "MX", "BR", "AR", "CL", "CO", "PE", "GB", "IE", "FR", "DE", "ES", "IT", "NL", "BE", "PT", "CH", "AT", "SE", "NO", "DK", "FI", "PL", "CZ", "GR", "RO", "HU", "TR", "IL", "AE", "SA", "EG", "ZA", "NG", "KE", "MA", "IN", "PK", "BD", "ID", "PH", "VN", "TH", "MY", "SG", "JP", "KR", "TW", "HK", "AU", "NZ" ], "type": "string", "description": "Country whose Ad Library to query. Use 'ALL' to search every country at once. Applied to Search Terms and Advertiser Pages; URLs in 'Ad Library URLs' use whatever country is encoded in the URL.", "default": "ALL" }, "adActiveStatus": { "title": "Ad Status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Whether to return only currently-running ads, only stopped/inactive ads, or both. The Ad Library marks ads ACTIVE while they're still being delivered and INACTIVE once they've stopped.", "default": "ALL" }, "adType": { "title": "Ad Category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "Meta groups ads into transparency categories. 'All ads' covers every public ad. The other categories surface political/issue, housing, employment, and credit ads where Meta provides additional disclosures (audience estimates, sometimes spend).", "default": "ALL" }, "mediaType": { "title": "Media Type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "NONE" ], "type": "string", "description": "Restrict results by creative format.", "default": "ALL" }, "publisherPlatforms": { "title": "Publisher Platforms", "uniqueItems": true, "type": "array", "description": "Only include ads that ran on these Meta surfaces. Leave empty to include every platform.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "THREADS", "WHATSAPP" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp" ] }, "default": [] }, "languages": { "title": "Ad Languages", "uniqueItems": true, "type": "array", "description": "Only include ads whose creative is in one of these languages. Leave empty for any language.", "items": { "type": "string", "enum": [ "en", "es", "pt", "fr", "de", "it", "nl", "pl", "tr", "ru", "ar", "he", "ja", "ko", "zh", "hi", "id", "th", "vi" ], "enumTitles": [ "English", "Spanish", "Portuguese", "French", "German", "Italian", "Dutch", "Polish", "Turkish", "Russian", "Arabic", "Hebrew", "Japanese", "Korean", "Chinese", "Hindi", "Indonesian", "Thai", "Vietnamese" ] }, "default": [] }, "dateFrom": { "title": "Earliest Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only include ads that first ran on or after this date (YYYY-MM-DD). Leave empty for no lower bound." }, "dateTo": { "title": "Latest Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only include ads that first ran on or before this date (YYYY-MM-DD). Leave empty for no upper bound." }, "includeAboutPage": { "title": "Enrich with advertiser page data", "type": "boolean", "description": "Look up each advertiser's Facebook page and attach extra fields (category, like count, verified flag, linked Instagram handle, follower count). Each enriched row is billed at the additional 'Advertiser details' rate (see Pricing). Leave off unless you need the page metadata. Disabled when 'Only return total count' is on.", "default": false }, "scrapeAdDetails": { "title": "Include creative details", "type": "boolean", "description": "Attach creative-level details to every ad row (CTA link, headline, card description, snapshot URL, and CTA button label). Each row that gets these fields is billed at the additional 'Creative details' rate (see Pricing). Disabled when 'Only return total count' is on.", "default": false }, "onlyTotalCount": { "title": "Only return total count", "type": "boolean", "description": "Pre-flight mode — return one row per source containing only the total matching-ad count. Useful for sizing a job before committing budget. Each summary row is billed at the 'Total count' rate (much cheaper than full ad collection). Ad rows are not produced and enrichment toggles are ignored.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 0, "type": "integer", "description": "Cap on total ads collected across every source. Set to 0 for unlimited (the run will keep paginating until Meta returns no more results). Each row is billed at the base 'Ad' rate (plus any enrichment surcharges).", "default": 100 } } }, "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 } } } } } } } } } } ```