# Facebook Ads Library Scraper (`socialdataapi/facebook-ads-library-scraper`) Actor Facebook Ads Library Scraper β€” Extract public Facebook Ads Library data including ad creatives, advertiser names, ad text, platforms, start dates, landing page URLs, and ad details. Useful for competitor research, ad intelligence, creative analysis, and marketing insights. - **URL**: https://apify.com/socialdataapi/facebook-ads-library-scraper.md - **Developed by:** [Social Data API](https://apify.com/socialdataapi) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.99 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ### Facebook Ads Library Scraper β€” Extract Ads, Creatives and Pages Facebook Ads Library Scraper pulls every matching ad, its creative, and the advertiser's page context straight from Meta's public Ad Library β€” point it at a Facebook Page URL or an Ad Library search link and it returns one typed record per ad. Every response is **structured JSON** β€” ready to pass directly into an LLM, index into a vector store, or feed a competitor ad-tracking pipeline. No Facebook account or login is needed to run it. Start with one competitor's Page, then scale to every advertiser you track. ![Facebook Ads Library Scraper hero: ads, creatives, dates and advertiser pages as JSON](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/b-facebook-ads-library-hero.webp) *** ### What data can I extract with Facebook Ads Library Scraper? Using this Facebook Ads Library API, you will be able to extract the following Facebook ad data: | πŸ†” Archive ID | 🏒 Page name & ID | 🟒 Active status | πŸ“… Start & end dates | | --- | --- | --- | --- | | 🌍 Platforms placed on | πŸ‘€ Reach estimate (political/issue ads) | πŸ’΅ Spend range (political/issue ads) | πŸ” Ad variant count | | ⏳ Total active time | πŸ–ΌοΈ Creative β€” images, video, carousel cards | πŸ’¬ Ad copy, title and CTA | πŸ”— Landing-page link | | 🏷️ Advertiser categories | πŸ‘ Page like count | ℹ️ Page "about" snippet (optional) | πŸ“„ Source URL | *** ### How to use Facebook Ads Library Scraper Anyone tracking a competitor's Facebook ad strategy, auditing political ad disclosures, or feeding ad creative into an AI pipeline can run this Actor once and get every matching ad back as structured data. **Copy to your AI assistant:** ```text Facebook Ads Library Scraper (Apify Actor ID: socialdataapi/facebook-ads-library-scraper, https://apify.com/socialdataapi/facebook-ads-library-scraper) is an Apify Actor that returns Meta Ad Library ads as structured JSON: archive ID, page name and ID, active status, start and end dates, platforms, creative (images, video, cards, copy), and advertiser page context. Use it whenever someone needs Facebook ad data without a login, a Facebook account, or a browser - tracking a competitor's active ads, auditing political ad disclosures, or feeding ad creative into a RAG pipeline. Run it through the Apify API's run-sync-get-dataset-items endpoint, or with the Apify Python client, using this Actor's ID from its own Apify Console page. Inputs: startUrls (array, Facebook Page URLs or Ad Library search links, one source per entry, each optionally with its own label, limit or period), resultsLimit (integer, 1-50000, default 10, caps ads across all sources combined), onlyTotal (boolean, default false, one summary row per source instead of one row per ad), includeAboutPage (boolean, default false, attaches a page "about" snippet), isDetailsPerAd (boolean, default true, runs a deeper per-ad lookup for richer fields), countryCode (string, default ALL), period (string, optional absolute date or relative time window), activeStatus (string: all | active | inactive, default all), proxyConfiguration (object, optional residential-only routing). When onlyTotal is on, each source returns one row with a total ad count instead of one row per ad, charged the same way as any other row. Full input schema, every enum and default, and the complete output field list are on this Actor's Apify Console page. ``` #### Facebook Ads Library Scraper MCP Server: use this Actor from ChatGPT, Claude or Cursor An MCP-connected agent can find and call this Actor directly through the Apify MCP server's search, add, and call-actor tools β€” no glue code, no scraping logic in your prompts. ```bash claude mcp add --transport http apify "https://mcp.apify.com?tools=socialdataapi/facebook-ads-library-scraper" ``` #### Step by step 1. [Create a free Apify account](https://console.apify.com/sign-up). 2. Open [**Facebook Ads Library Scraper**](https://apify.com/socialdataapi/facebook-ads-library-scraper) in the Apify Store. 3. Enter a Facebook Page URL or an Ad Library search link. 4. Click **Start** (or send your API request). 5. Download or stream your results in JSON, CSV or Excel. #### How to scale Facebook Ads Library Scraper to bulk Add more than one source to the sources list in the same run β€” mix Facebook Page URLs and Ad Library search links freely, and give any entry its own ad limit or time window to override the run-wide defaults. The maximum-ads setting then caps the combined total across every source, so one scheduled run can track a whole list of competitor Pages and keyword searches together. For a larger set of Pages than fits in one run, loop the same input with a different source list per call through the Apify API, or chain several scheduled runs with non-overlapping source lists. *** ### ✨ Features Facebook Ads Library Scraper fetches clean, structured ads from Meta's public Ad Library ⚑, billed per ad row actually written to the dataset. It's ideal for competitor ad tracking, political ad spend research, creative-analysis pipelines, and ad-intelligence dashboards. It extracts, per ad: - **Archive ID and page info** – which advertiser ran the ad, and its Facebook page ID - **Active status and run dates** – whether the ad is still running, and when it started and ended - **Platform placement** – which surfaces it ran on (Facebook, Instagram, Messenger, Audience Network) - **Ad creative** – body text, title, CTA, link, images, video, and carousel cards - **Variant count** – how many creative variants Meta groups under the same ad - **Advertiser page context** – page categories, like count, and an optional "about" snippet - **Transparency fields** – spend range, reach estimate and targeted countries, where Meta discloses them for political/issue ads ⚑ A count-only mode returns a single total per source instead of a full creative pull, for a fast audit before committing to a large run. *** ### Use cases πŸ’‘ - **Brand marketer** β€” track a competitor's active Facebook ads by platform and creative format. - **Political researcher** β€” pull political and issue-ad spend and reach disclosures by Page. - **AI engineer** β€” feed Facebook ad creative text into a RAG pipeline for competitive-intelligence chat. - **Growth analyst** β€” export every ad a Page has run and diff new archive IDs on a schedule. - **Agency** β€” audit a client's ad library coverage with count-only mode before a full pull. Building an AI agent? [Connect Facebook Ads Library Scraper over MCP](#facebook-ads-library-scraper-mcp-server-use-this-actor-from-chatgpt-claude-or-cursor) and let it call the actor on its own. *** ### Why choose this actor? - **Two ways to query, one Actor.** Point it at a Facebook Page URL to pull one advertiser's ads, or an Ad Library search link for a keyword and country search β€” both in the same source list, in the same run. - **The full creative behind every ad.** Each row returns the ad's copy, title, CTA, images, video and carousel cards alongside its archive ID, dates and platform placement, in one normalized JSON object. - **A fast audit before a full pull.** Switch on count-only mode and get one total per source instead of paying for a full creative pull, then scale up to 50,000 ads per run once you know what you need. *** ### ⬇️ Input ![Facebook Ads Library Scraper input: startUrls, resultsLimit, onlyTotal and activeStatus](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/b-facebook-ads-library-input.webp) It accepts one or more Facebook Page URLs or Ad Library search links as its sources; no field is required, so an empty input still runs against the prefilled example sources. | Parameter | Required | Type | Description | Example Value | | --- | --- | --- | --- | --- | | `startUrls` | No | array | Facebook Page URLs or Ad Library links, one source per entry. Plain strings, or objects with a `url` field (and optional `label`, `limit`, `period`). | `["https://www.facebook.com/SHEINOFFICIAL"]` | | `resultsLimit` | No | integer | Upper bound on ads returned across **all** sources in the run. Min `1`, max `50000`. Default `10`. | `20` | | `onlyTotal` | No | boolean | Instead of one row per ad, output one summary row per source with a total count. Default `false`. | `false` | | `includeAboutPage` | No | boolean | For Facebook Page sources, attach a lightweight public title/description "about" snippet. Default `false`. | `true` | | `isDetailsPerAd` | No | boolean | Run an additional per-ad lookup for richer metadata (more complete rows, slower run). Default `true`. | `true` | | `countryCode` | No | string (enum) | Default country for Page sources (`ALL` or an ISO code such as `US`, `GB`, `DE`). Ad Library links usually carry their own country. Default `ALL`. | `"US"` | | `period` | No | string | Optional time window when the source URL doesn't specify one. Absolute date (`YYYY-MM-DD`) or relative span (`7 days`, `1 month`, `1 year`). Empty follows the library's own default. | `"30 days"` | | `activeStatus` | No | string (enum) | Filter for Page sources, or when a search link leaves it unspecified: `all`, `active`, `inactive`. Default `all`. | `"active"` | | `proxyConfiguration` | No | object | Optional Apify Proxy. When enabled, the whole run uses **residential** endpoints only. Requires proxy access on your Apify plan. | `{"useApifyProxy": true}` | #### Example input ```json { "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&search_type=keyword_unordered&q=shoes" ], "resultsLimit": 20, "onlyTotal": false, "includeAboutPage": true, "isDetailsPerAd": true, "countryCode": "US", "period": "30 days", "activeStatus": "active", "proxyConfiguration": { "useApifyProxy": true } } ``` The maximum-ads setting caps ads across **all** sources combined, not per source β€” to cap one source individually, set a `limit` (and optionally its own `period`) on that entry's object inside the sources list instead of relying on the run-wide default. #### Free plan limits Free plan: up to 20 ads per run (all sources together) and 200 per month; paid plans have no limit. *** ### ⬆️ Output ![Facebook Ads Library Scraper output: adArchiveID, isActive, publisherPlatform and snapshot fields](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/b-facebook-ads-library-output.webp) Every ad is written to the run's default dataset as one typed JSON object, with the same field names and types on every run. Export it as JSON, CSV, or Excel from the Apify Console, or read it through the Apify API. This Actor is billed per ad row actually written to the dataset. #### Example output ```json { "inputUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&sort_data[direction]=desc&sort_data[mode]=total_impressions&view_all_page_id=15087023444", "pageID": "15087023444", "pageId": "15087023444", "adArchiveID": "1234567890123456", "adArchiveId": "1234567890123456", "adId": null, "startDate": 1748736000, "endDate": 1751328000, "startDateFormatted": "2025-06-01T00:00:00.000Z", "endDateFormatted": "2025-07-01T00:00:00.000Z", "isActive": true, "totalActiveTime": 2592000, "publisherPlatform": ["FACEBOOK", "INSTAGRAM"], "collationCount": 3, "collationId": "9876543210", "categories": [], "gatedType": null, "hideDataStatus": null, "isAaaEligible": false, "containsSensitiveContent": false, "containsDigitalCreatedMedia": false, "hasUserReported": false, "reportCount": null, "menuItems": [], "stateMediaRunLabel": null, "pageIsDeleted": false, "pageName": "SHEIN Official", "reachEstimate": null, "spend": null, "currency": "", "impressionsWithIndex": { "impressionsText": null, "impressionsIndex": -1 }, "targetedOrReachedCountries": [], "regionalRegulationData": {}, "fevInfo": null, "snapshot": { "pageId": "15087023444", "pageName": "SHEIN Official", "title": "SHEIN Official", "body": { "text": "Up to 70% off summer styles β€” shop the new drop." }, "caption": "shein.com", "ctaText": "Shop Now", "ctaType": "SHOP_NOW", "linkUrl": "https://shein.com/campaign/summer", "linkDescription": "Free shipping on orders over $49", "displayFormat": "IMAGE", "images": [{ "url": "https://scontent.xx.fbcdn.net/v/creative_123.jpg" }], "videos": [], "cards": [], "pageCategories": ["Clothing (Brand)"], "pageLikeCount": 28500000, "countryIsoCode": "US" }, "pageInfo": { "page": { "name": "SHEIN Official", "id": "15087023444", "url": "https://www.facebook.com/SHEINOFFICIAL", "about": { "text": "Global online fashion retailer." } }, "adLibraryPageInfo": { "pageInfo": { "hasBlankAds": false, "hiddenAds": 0, "pageIsDeleted": false } } } } ``` When count-only mode is enabled, each source produces one row like this instead of one row per ad: ```json { "sourceUrl": "https://www.facebook.com/SHEINOFFICIAL", "label": "Source 1", "totalAdsCount": 842, "aboutPage": { "url": "https://www.facebook.com/SHEINOFFICIAL", "title": "SHEIN Official", "description": "Global online fashion retailer." } } ``` The page "about" snippet field only appears when that option is also enabled. *** ### How does it work? Facebook Ads Library Scraper reads the same public pages the Meta Ad Library website loads, over plain HTTP requests β€” no browser is opened. It connects the way an ordinary visitor's browser does, automatically clears Meta's anti-bot challenge when one is served, and escalates from a direct connection to Apify's residential proxy network if a request gets blocked, all without any setup on your side. It only ever returns what the public Ad Library page already shows for a given Page or search β€” no login, no private data, and no content from behind a personal profile. The output schema is normalized and kept stable: field names and types stay the same in your integration even when Meta changes the Ad Library's own internals, so your pipeline keeps working after an update. *** ### How do you integrate Facebook Ads Library Scraper into your stack? It works with what you already use: a REST API callable from any language, an MCP server for AI agents, and no-code automation tools. #### Using Facebook Ads Library Scraper with the Apify API Open this Actor's **API** tab on its Apify Console page for a ready-to-copy request in cURL, Python, and Node.js, already filled in with this Actor's ID and your own token. In outline, it's a single `POST` to the Apify `run-sync-get-dataset-items` endpoint for this Actor, with your input (for example `{"startUrls": ["https://www.facebook.com/SHEINOFFICIAL"], "resultsLimit": 20}`) as the JSON body, which returns the scraped ad rows directly in the response. *Works in Go, Ruby, Node.js, cURL β€” any language that can make an HTTP request.* #### MCP integration for AI agents Registering the Apify MCP server, as shown above, lets an agent search for, add, and call this Actor as a tool on its own β€” no actor ID needed up front. Compatible with Claude Code, Cursor, and Windsurf. #### No-code tools (n8n, Make, LangChain) In **n8n**, use the Apify node's "Run an Actor" action (or the HTTP Request node pointed at the run-sync endpoint with your token) and pick this Actor. In **Make**, use the Apify app's "Run an Actor" module followed by "Get Dataset Items." In **LangChain**, use the `langchain-apify` package's `ApifyActorsTool`, passed this Actor's ID from its Console page. *** ### Is it legal to scrape Facebook? Yes β€” scraping Meta's Ad Library is legal when you collect only the public data Meta already publishes for transparency. Facebook Ads Library Scraper returns only what the public Ad Library page shows: it does not log in and does not access private accounts. Most of what it collects is business and advertiser data β€” page names, ad creatives, and spend or reach disclosures β€” which sits under Meta's Terms of Service rather than personal-data law, though some fields (such as an individual's name on a personal-brand or political advertiser page) can be personal data under GDPR or CCPA, so you need a lawful basis before storing or reusing that data in bulk. Consult legal counsel if your use case involves bulk storage of personal data. *** ### Frequently asked questions #### What fields does Facebook Ads Library Scraper return? The top fields are archive ID, page name and ID, active status, start and end dates, and platform placement β€” see [the data fields section](#what-data-can-i-extract-with-facebook-ads-library-scraper) for the full list. #### Does Facebook Ads Library Scraper require a Facebook account or login? No. The Actor runs fully logged out against the public Ad Library β€” no Facebook account, password, or session cookie is required. #### What happens if a Page can't be found or a search returns no ads? If a Page URL can't be resolved to a page ID, the Actor logs an error for that source and continues with the others rather than failing the whole run. If a source matches zero ads, it simply contributes no rows to the dataset. #### Can I scrape multiple Facebook Ad Library sources at once? Yes. Add as many Facebook Page URLs and Ad Library search links as you want to the same sources list in one run β€” mix both types freely, and give any entry its own ad limit or time window. #### Does Facebook Ads Library Scraper work with Claude, ChatGPT, and other AI agent tools? Yes β€” it's reachable as a tool through the Apify MCP server (see the MCP sections above), and any agent framework that can call an HTTP endpoint can use the REST API directly. #### Does Facebook Ads Library Scraper return data in a format LLMs can use directly? Yes. Typed, normalized JSON with stable field names β€” no HTML, no selectors. Pass it directly into an LLM context window, index it into a vector store, or route it through an agent tool. #### What happens when Facebook changes its structure or blocks the scraper? This Actor is actively maintained: its output schema is designed to stay stable, so field names and types keep working in your integration even when Meta changes the Ad Library's underlying internals or anti-bot checks. #### Can I use Facebook Ads Library Scraper without managing proxies or browser infrastructure? Yes. By default the Actor connects directly and only escalates to Apify's residential proxy network on its own if Facebook blocks the request. You send one request and get structured JSON back β€” no proxy accounts, no headless browser setup, no maintenance. #### Which Facebook ad fields work best for AI training data and RAG indexing? For RAG: the text-rich fields β€” ad copy, title, caption, and the advertiser's page "about" snippet. For training data: the numeric and boolean fields β€” active status, total active time, variant count, reach estimate, and spend. All fields are typed primitives (strings, integers, booleans), so no normalization step is needed. *** ### Your feedback Found a bug or missing a field? We want to know. Report it through this Actor's Issues tab on Apify Console β€” every report gets reviewed, and fixes ship as Meta's Ad Library evolves. # Actor input Schema ## `startUrls` (type: `array`): One entry per line. You can paste plain URLs, or use objects with a `url` field (optional `label`, `limit`, or `period` per item). ## `resultsLimit` (type: `integer`): Upper bound on ads returned **across all sources** in this run. Lower = faster and lighter; higher = broader coverage. Free plan: up to 20 ads per run (all sources together) and 200 per month; paid plans have no limit. ## `onlyTotal` (type: `boolean`): Instead of one row per ad, output **one summary row per source** with a total countβ€”handy for quick audits. ## `includeAboutPage` (type: `boolean`): For **Facebook page** sources, attach lightweight public title/description text when available. ## `isDetailsPerAd` (type: `boolean`): Runs an additional lookup per ad for richer metadata (more complete rows; slower runs). Turn off for a lighter listing-only export. ## `countryCode` (type: `string`): Region used for **Facebook page** sources. Library URLs usually carry their own country in the link. ## `period` (type: `string`): Optional window when your URL does not already specify one. **Leave empty** to follow the library’s own default. Pick a calendar date or a relative span (e.g. 7 days)β€”values are passed through as you provide them. ## `activeStatus` (type: `string`): Filter for **page** sources, or when your Ad Library link leaves this unspecified. ## `proxyConfiguration` (type: `object`): Leave off for a standard run. If you enable Apify Proxy here, **only residential** proxy traffic is used for the whole run. Requires proxy access on your Apify plan. ## Actor input object example ```json { "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&media_type=all&search_type=keyword_unordered" ], "resultsLimit": 10, "onlyTotal": false, "includeAboutPage": false, "isDetailsPerAd": true, "countryCode": "ALL", "period": "", "activeStatus": "all", "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `results` (type: `string`): All scraped items in the Actor's default dataset. # 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 = { "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&media_type=all&search_type=keyword_unordered" ], "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("socialdataapi/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 = { "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&media_type=all&search_type=keyword_unordered", ], "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("socialdataapi/facebook-ads-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&media_type=all&search_type=keyword_unordered" ], "proxyConfiguration": { "useApifyProxy": false } }' | apify call socialdataapi/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,socialdataapi/facebook-ads-library-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/wqSpxzu3DfJezSTRK/builds/sixh7fQ0ePKqj1IPe/openapi.json