# Facebook Ads Library Scraper — Meta & Instagram Ads (`brilliant_gum/facebook-ads-library-scraper`) Actor Extract ads from the Meta Ads Library (Facebook & Instagram). Get ad copy, running days, EU spend data, carousel cards, and landing page URLs. The only scraper that tracks how long each ad has been running — your key signal for finding competitor winning ads. - **URL**: https://apify.com/brilliant\_gum/facebook-ads-library-scraper.md - **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community) - **Categories:** Social media - **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $15.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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

Collect · Analyze · Outperform
The most data-rich Facebook Ads Library scraper on Apify —
daysRunning, structured spend ranges, full carousel cards, video URLs, and landing pages.

Why this one? · Input · Output · Use cases · Pricing

--- **Facebook Ads Library Scraper** extracts ads from the [Meta Ads Library](https://www.facebook.com/ads/library/) — Meta's public database of every ad running on Facebook, Instagram, Messenger, Threads, and Audience Network. Built for marketers, agencies, and researchers who need **clean, structured data** — not raw HTML or incomplete JSON. Every field is normalized, deduped, and ready to pipe into your analysis tool or CRM. --- ### ✨ What makes this different | Feature | This actor | Most others | |---|---|---| | `daysRunning` — how long the ad has been live | ✅ computed automatically | ❌ | | Spend as structured `{min, max}` — not a raw string | ✅ | ❌ | | All carousel cards extracted as individual objects | ✅ | First card only | | Video URLs (fbcdn.net CDN) | ✅ | ❌ | | Image URLs for all image ads | ✅ | ❌ | | Landing page URL via `resolveSnapshotUrls` | ✅ opt-in | ❌ | | Cross-search deduplication | ✅ | ❌ | | Login wall detection with clear error message | ✅ | ❌ | | Filters: status, ad category, date range, country | ✅ | Partial | --- ### 💡 Why `daysRunning` is the most valuable field > **An ad running for 60+ days is profitable.** The advertiser keeps paying because it converts. `daysRunning` lets you instantly separate **proven winners** from tests without any manual calculation. Sort by it descending and you have a ranked list of your competitor's best-performing creatives — right now. No other Facebook ads scraper on Apify computes this field automatically. --- ### ⚙️ Input | Field | Type | Default | Description | |---|---|---|---| | `searchTerms` | string[] | `["Nike"]` | Brand names or keywords to search | | `countries` | string[] | `["US"]` | ISO 2-letter country codes (e.g. `"US"`, `"GB"`, `"DE"`) | | `adType` | string | `"ALL"` | `ALL` · `POLITICAL_AND_ISSUE_ADS` · `HOUSING` · `EMPLOYMENT` · `FINANCIAL_PRODUCTS_AND_SERVICES` | | `adActiveStatus` | string | `"ACTIVE"` | `ALL` · `ACTIVE` · `INACTIVE` | | `maxAds` | integer | `25` | Max ads per search term + country pair | | `resolveSnapshotUrls` | boolean | `false` | Visit each ad snapshot page to extract the real landing page URL and CDN media files | | `startDate` | string | — | Show ads that were active on/after this date (`YYYY-MM-DD`) | | `endDate` | string | — | Show ads that were active on/before this date (`YYYY-MM-DD`) | > **Note on date filters:** Meta shows ads that were *running during* the specified period, which may include ads that started before `startDate` if they were still active within your range. This is Meta's behavior, not a scraper limitation. #### Example inputs **Quick test — Nike US active ads** ```json { "searchTerms": ["Nike"], "countries": ["US"], "adActiveStatus": "ACTIVE", "maxAds": 25 } ```` **Agency competitor research — 3 brands × 3 countries** ```json { "searchTerms": ["Adidas", "Nike", "Puma"], "countries": ["US", "GB", "DE"], "adActiveStatus": "ACTIVE", "maxAds": 200 } ``` **Political ads with spend data (EU/DSA)** ```json { "searchTerms": ["election"], "countries": ["DE"], "adType": "POLITICAL_AND_ISSUE_ADS", "adActiveStatus": "ALL", "maxAds": 100 } ``` **Date range — ads from a specific campaign window** ```json { "searchTerms": ["Nike"], "countries": ["US"], "adActiveStatus": "ALL", "maxAds": 50, "startDate": "2025-01-01", "endDate": "2025-06-30" } ``` **resolveSnapshotUrls — get real landing page URLs** ```json { "searchTerms": ["Nike"], "countries": ["US"], "adActiveStatus": "ACTIVE", "maxAds": 20, "resolveSnapshotUrls": true } ``` *** ### 📦 Output schema Each item in the dataset represents **one ad**. Carousel ads include all cards as separate objects inside `creatives`. ```json { "adArchiveId": "1234567890", "pageId": "987654321", "pageName": "Nike", "adActiveStatus": "ACTIVE", "adDeliveryStartTime": "2025-11-01T00:00:00.000Z", "adDeliveryStopTime": null, "daysRunning": 154, "publisherPlatforms": ["facebook", "instagram"], "mediaType": "VIDEO", "creativeVariantCount": 3, "creatives": [ { "body": "Just Do It. Shop the new Air Max collection.", "title": "Air Max 2026", "caption": "nike.com", "description": null, "ctaText": "Shop Now", "ctaType": "SHOP_NOW", "destinationUrl": "https://www.nike.com/air-max", "imageUrls": [], "videoUrl": "https://video.ftbs6-2.fna.fbcdn.net/...", "cardIndex": 0 } ], "spend": { "min": 1000, "max": 5000 }, "impressions": { "min": 100000, "max": 500000 }, "estimatedAudienceSize": { "min": 1000000, "max": 2000000 }, "demographicDistribution": null, "euTotalReach": null, "targetAges": null, "targetGender": null, "targetLocations": null, "bylines": null, "fundingEntity": null, "snapshotUrl": "https://www.facebook.com/ads/library/?id=1234567890", "scrapedAt": "2026-04-04T12:00:00.000Z" } ``` #### Field reference | Field | Type | Notes | |---|---|---| | `adArchiveId` | string | Unique Meta ad ID | | `pageName` | string | Advertiser page name | | `adActiveStatus` | string | `ACTIVE` or `INACTIVE` | | `daysRunning` | integer | Days since ad delivery start — key profitability signal | | `publisherPlatforms` | string\[] | e.g. `["facebook", "instagram", "messenger", "threads"]` | | `mediaType` | string | `VIDEO`, `IMAGE`, or `NONE` | | `creatives` | object\[] | All creative variants; carousel = multiple objects | | `creatives[].body` | string | Ad copy text | | `creatives[].videoUrl` | string | Direct CDN video URL (fbcdn.net) | | `creatives[].imageUrls` | string\[] | Direct CDN image URLs (fbcdn.net) | | `creatives[].destinationUrl` | string | Landing page URL — from GraphQL when available, or via `resolveSnapshotUrls` | | `spend` | object | `{min, max}` in USD — see availability note below | | `impressions` | object | `{min, max}` — see availability note below | | `estimatedAudienceSize` | object | `{min, max}` potential reach | | `demographicDistribution` | object | Age/gender breakdown (political ads only) | | `fundingEntity` | string | Who paid for the ad (political ads only) | #### Spend & impressions availability | Ad type | `spend` & `impressions` | |---|---| | US / global commercial ads (Nike, Adidas, etc.) | `null` — Meta policy, not a scraper bug | | EU/UK commercial ads | Available for some ad categories under DSA | | Political, issue, housing, employment, financial ads | ✅ Returned as `{min, max}` objects | *** ### 🎯 Use cases **Competitor ad intelligence** Find which creatives your competitors have kept running for 60, 90, 120+ days. Long-running = profitable. Build a swipe file of proven winners, not guesses. **Agency client reporting** Bulk-export all active ads for a brand across every country and platform. Export to CSV, Google Sheets, or push straight into your reporting dashboard via Apify API. **Creative benchmarking** What CTAs dominate your category? Which formats (video vs. image vs. carousel) are brands investing in? What copy angles are getting budget behind them? **Political ad monitoring** EU/UK DSA transparency data: spend ranges, estimated reach, demographic targeting, and funding entity — all structured and ready for analysis. **Market research & trend tracking** Run the same search weekly to track how competitors shift their messaging, seasonal spend, and creative strategy over time. *** ### 💰 Pricing **From $15.00 / 1,000 ads** — no monthly fees, pay only for what you scrape. | Mode | What you get | ~Total cost per 1,000 ads | |---|---|---| | Standard | All fields — copy, video URLs, image URLs, spend, all carousel cards | **~$15** | | `resolveSnapshotUrls: true` | Everything above + confirmed landing page URL for each ad | **~$16–17** | > `resolveSnapshotUrls` mode visits an extra page per ad (~5 sec each), which adds some Apify platform compute time on top of the base price. No monthly fees — pay only for what you scrape. *** ### ⚠️ Limitations - **Spend/impressions** are `null` for US commercial ads. This is Meta's transparency policy — data is only disclosed for political/issue/housing/employment/financial ads and some EU ads under DSA rules. - Meta does not expose **exact spend** — only ranges (e.g. $1,000–$5,000). - **`resolveSnapshotUrls`** adds ~5 seconds per ad (one extra page load). For 1,000 ads, budget ~90 minutes of run time. - Date range filters rely on Meta's own filtering, which may include ads that started before your `startDate` if they were still active during your range. - Meta periodically updates their internal page structure. If you notice empty results, open an issue and we'll push an update within 24–48 hours. # Actor input Schema ## `searchTerms` (type: `array`): Keywords or brand names to search in the Meta Ads Library. Each term is searched separately. ## `countries` (type: `array`): ISO 2-letter country codes (e.g. US, GB, DE). Each country is queried separately per search term. ## `adType` (type: `string`): Filter by ad category. 'All Ads' returns every category. Political, Housing, Employment and Financial ads have additional spend/reach data in EU/UK. ## `adActiveStatus` (type: `string`): Filter by whether ads are currently running. ## `maxAds` (type: `integer`): Maximum number of ads to collect per search term + country combination. Keep under 50 for a quick test run. ## `resolveSnapshotUrls` (type: `boolean`): Visit each ad's snapshot page to extract the real landing page URL and CDN media file URLs (images/videos). Slower — adds ~5 sec per ad. Disable for bulk collection, enable when you need destination URLs. ## `startDate` (type: `string`): Only include ads that started running on or after this date. Format: YYYY-MM-DD. Leave empty to skip. ## `endDate` (type: `string`): Only include ads that started running on or before this date. Format: YYYY-MM-DD. Leave empty to skip. ## Actor input object example ```json { "searchTerms": [ "Nike" ], "countries": [ "US" ], "adType": "ALL", "adActiveStatus": "ACTIVE", "maxAds": 25, "resolveSnapshotUrls": false, "startDate": "", "endDate": "" } ``` # Actor output Schema ## `adArchiveId` (type: `string`): Unique Meta ad archive identifier ## `pageName` (type: `string`): Name of the advertising page ## `adActiveStatus` (type: `string`): ACTIVE or INACTIVE ## `daysRunning` (type: `string`): Number of days the ad has been or was running ## `mediaType` (type: `string`): VIDEO, IMAGE, or NONE ## `adDeliveryStartTime` (type: `string`): ISO 8601 date when the ad started running ## `adDeliveryStopTime` (type: `string`): ISO 8601 date when the ad stopped, or null if still active ## `publisherPlatforms` (type: `string`): Platforms where the ad ran: facebook, instagram, messenger, threads ## `creatives` (type: `string`): Creative variants — each carousel card is a separate object ## `spend` (type: `string`): {min, max} spend range in USD — EU/political ads only ## `impressions` (type: `string`): {min, max} impression range — EU/political ads only ## `estimatedAudienceSize` (type: `string`): {min, max} potential reach ## `snapshotUrl` (type: `string`): Link to the ad in Meta Ads Library ## `scrapedAt` (type: `string`): ISO 8601 timestamp of when the ad was scraped # 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" ], "countries": [ "US" ] }; // Run the Actor and wait for it to finish const run = await client.actor("brilliant_gum/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 = { "searchTerms": ["Nike"], "countries": ["US"], } # Run the Actor and wait for it to finish run = client.actor("brilliant_gum/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 '{ "searchTerms": [ "Nike" ], "countries": [ "US" ] }' | apify call brilliant_gum/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=brilliant_gum/facebook-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper — Meta & Instagram Ads", "description": "Extract ads from the Meta Ads Library (Facebook & Instagram). Get ad copy, running days, EU spend data, carousel cards, and landing page URLs. The only scraper that tracks how long each ad has been running — your key signal for finding competitor winning ads.", "version": "1.0", "x-build-id": "JMYmgiQU4zrbPcTi6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/brilliant_gum~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-brilliant_gum-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/brilliant_gum~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-brilliant_gum-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/brilliant_gum~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-brilliant_gum-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", "required": [ "searchTerms" ], "properties": { "searchTerms": { "title": "Search Terms", "type": "array", "description": "Keywords or brand names to search in the Meta Ads Library. Each term is searched separately.", "default": [ "Nike" ], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "ISO 2-letter country codes (e.g. US, GB, DE). Each country is queried separately per search term.", "default": [ "US" ], "items": { "type": "string" } }, "adType": { "title": "Ad Category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING", "EMPLOYMENT", "FINANCIAL_PRODUCTS_AND_SERVICES" ], "type": "string", "description": "Filter by ad category. 'All Ads' returns every category. Political, Housing, Employment and Financial ads have additional spend/reach data in EU/UK.", "default": "ALL" }, "adActiveStatus": { "title": "Ad Status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Filter by whether ads are currently running.", "default": "ACTIVE" }, "maxAds": { "title": "Max Ads Per Search", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Maximum number of ads to collect per search term + country combination. Keep under 50 for a quick test run.", "default": 25 }, "resolveSnapshotUrls": { "title": "Resolve Snapshot URLs", "type": "boolean", "description": "Visit each ad's snapshot page to extract the real landing page URL and CDN media file URLs (images/videos). Slower — adds ~5 sec per ad. Disable for bulk collection, enable when you need destination URLs.", "default": false }, "startDate": { "title": "Start Date Filter (YYYY-MM-DD)", "type": "string", "description": "Only include ads that started running on or after this date. Format: YYYY-MM-DD. Leave empty to skip.", "default": "" }, "endDate": { "title": "End Date Filter (YYYY-MM-DD)", "type": "string", "description": "Only include ads that started running on or before this date. Format: YYYY-MM-DD. Leave empty to skip.", "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 } } } } } } } } } } ```