# Facebook Ads Library Scraper \[💰$0.05/1k] (`blackfalcondata/facebook-ads-library-scraper`) Actor Scrape facebook.com/ads/library by keyword or advertiser: ad copy, image and video URLs, landing page URL, start and end dates, and how many days each ad has run. Turn on EU transparency and every ad also carries its total EU reach with an age, gender and country breakdown. - **URL**: https://apify.com/blackfalcondata/facebook-ads-library-scraper.md - **Developed by:** [Black Falcon Data](https://apify.com/blackfalcondata) (community) - **Categories:** Social media, Lead generation, Automation - **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.05 / 1,000 ads 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/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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 ### What does Facebook Ads Library Scraper do? Facebook Ads Library Scraper exports live ads from Meta's Ad Library at [facebook.com/ads/library](https://www.facebook.com/ads/library) — by keyword, or every ad one advertiser is currently running. Each record carries the ad copy and headline, image and video URLs, every carousel card, the landing page URL and its domain, the platforms it runs on, and how many days it has been live. Turn on detail enrichment and every ad also carries its total EU reach with an age, gender and country breakdown of who saw it, plus the advertiser's Instagram handle, follower count and page description. **New to Apify?** [Sign up free](https://console.apify.com/sign-up?fpr=1h3gvi) and use the included $5 monthly platform credit to test this actor. ### Key features - **🇪🇺 EU reach and audience per ad:** turn on `includeDetails` and every ad carries `eu_total_reach`, plus `eu_age_country_gender_reach`: how many people in each EU country saw it, split by age band and gender. The targeting the advertiser set comes with it (`eu_gender_audience`, `eu_age_audience`, `eu_location_audience`), along with the advertiser's Instagram handle, follower count and page description. Ads that do not target the EU leave these empty — that is the source's own boundary, not a gap. - **🗳️ Spend and reach on political ads:** set Ad Category to "Political & issue ads" and every row carries the regulated disclosure: banded spend, reach and impressions as Meta reports them, plus `spend_lower` / `spend_upper` parsed into numbers you can sort, and the "paid for by" byline. Measured at 100% fill on that library. Commercial ads carry none of it — no tool has it — which is what the EU reach block above is for. - **🎬 The whole creative, not a link to it:** every record ships the ad copy and headline, the caption and call to action, image URLs and video URLs, each carousel card, the landing page URL and its domain. Dynamic-creative ads get their `placeholder-token` copy resolved from the rendered variant into `resolved_body` / `resolved_title`, which the raw column cannot give you. - **📆 How long each ad has been running:** `start_date`, `end_date` and `days_running` on every ad, with `end_date` left null while an ad is still live rather than filled with Meta's far-future placeholder. Long-running ads are the ones a competitor is spending on. - **🎯 One advertiser's entire lineup:** paste an Ad Library URL with `view_all_page_id` and the run returns every ad that advertiser is currently running, instead of a keyword match. - **🧬 The same creative under many ad ids:** `creative_hash` hashes the copy and media, so one creative running under several archive ids collapses to a single identity — which is what makes counting distinct creatives, rather than distinct ad records, possible. - **♻️ Incremental mode:** incremental mode keys state to the query and its filters, then delivers only ads that are new or changed since the last run. - **📦 Compact mode:** compact mode trims each record to the columns most runs actually read. - **🔔 Notifications:** Send new or changed ads to Telegram, Discord, Slack, WhatsApp or a generic webhook after each run. ### What data can you extract from Facebook Ads Library? Every record ships the advertiser (page name, profile URL, categories, likes), the full creative (ad copy, headline, caption, call to action, image URLs, video URLs, carousel cards), the destination (landing page URL and registrable domain), and the lifecycle (start date, end date, whether it is still running, and days running). Dynamic-creative ads get their `placeholder-token` copy resolved from the rendered variant. With detail enrichment on, each ad adds its EU reach and the per-country age/gender breakdown of who saw it, the targeting the advertiser set, and the advertiser's Instagram profile. Spend, impressions and reach come from two different places, and both are in the output. Set **Ad Category** to "Political & issue ads" and `spend`, `reach_estimate` and `impressions` fill on essentially every row — always as a band (`">$1M"`, `"$600K - $700K"`), with `spend_lower` / `spend_upper` parsed out for sorting, plus the "paid for by" byline. Meta publishes none of that for ordinary commercial advertising, for any tool: there the figures live in the EU transparency record instead, which is what `eu_total_reach` and `eu_age_country_gender_reach` carry when detail enrichment is on. `is_political` tells you which regime a row is under. ### Input The main inputs are a search keyword, an optional location filter, and a result limit. Additional filters and options are available in the input schema. Key parameters: - **`query`** — Keyword(s) to search the Ad Library for — a brand, product, or phrase that appears in the ad copy or advertiser name. Required if no startUrls provided. - **`startUrls`** — Paste raw Ad Library search URLs (https://www.facebook.com/ads/library/?q=...\&country=US or ?view\_all\_page\_id=...). Each URL becomes its own search task; results are merged and deduped by ad archive ID across all URLs. When provided AND parseable, startUrls REPLACE the query field. (default: `[]`) - **`country`** — Ad Library country the ads were delivered in. ALL searches every country. (default: `"US"`) - **`activeStatus`** — Only ads currently running, only ads that have stopped, or both. (default: `"ALL"`) - **`adType`** — Meta files some ads in regulated categories. "All ads" covers ordinary commercial advertising. Pick "Political & issue ads" to search the library Meta publishes spend, reach and impression figures for — those columns are filled only there, and come back empty on commercial ads. (default: `"ALL"`) - **`mediaType`** — Restrict to image ads, video ads, or memes. (default: `"ALL"`) - **`searchType`** — Match the search term as separate words, or as an exact phrase. (default: `"KEYWORD_UNORDERED"`) - **`publisherPlatforms`** — Only ads shown on these Meta platforms. Leave empty for all of them. (default: `[]`) - **`contentLanguages`** — ISO language codes, e.g. en, de, da. Leave empty for all languages. (default: `[]`) - **`startDateMin`** — Only ads that started running on or after this date (YYYY-MM-DD). - **`startDateMax`** — Only ads that started running on or before this date (YYYY-MM-DD). - **`maxResults`** — Maximum total ads to return. The Ad Library is cursor-paginated and hands back about 10 ads per request after the first page, so large numbers mean long runs. (default: `25`) - ...and 21 more parameters ### Input examples **Basic search** — Keyword-driven search with a result cap. → Full payload per result — all standard fields populated where the source provides them. ```json { "query": "nike", "maxResults": 50 } ``` **Incremental tracking** — Only emit changes that changed since the previous run with this `stateKey`. → First run builds the baseline state. Subsequent runs emit only records that are new or whose tracked content changed. Set `emitUnchanged: true` to include unchanged records as well. ```json { "query": "nike", "maxResults": 200, "incrementalMode": true, "stateKey": "nike-tracker" } ``` **Compact filtered output** — Combine filters with compact mode for a lightweight AI-agent or MCP data source. → Core fields only — ideal for piping into LLMs or downstream tools without token overhead. ```json { "query": "nike", "mediaType": "ALL", "maxResults": 50, "compact": true } ``` ### Output Each run produces a dataset of structured listing records. Results can be downloaded as JSON, CSV, or Excel from the Dataset tab in Apify Console. ### Example listing record ```json { "record_type": "ad", "ad_archive_id": "352695862528588", "library_url": "https://www.facebook.com/ads/library/?id=352695862528588", "portalUrl": "https://www.facebook.com/ads/library/?id=352695862528588", "page_id": "20531316728", "page_name": "Facebook", "page_profile_url": "https://www.facebook.com/facebook/", "page_profile_picture_url": "https://scontent.fcph2-1.fna.fbcdn.net/v/t39.35426-6/123254501_376431443560946_8642123156381274111_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Esww25XxDRcQ7kNvwFWvV7z&_nc_o...", "page_categories": [ "Website", "Company" ], "page_like_count": 154733101, "is_active": false, "start_date": "2020-08-27T07:00:00.000Z", "end_date": "2020-08-30T07:00:00.000Z", "source_end_date": "2020-08-30T07:00:00.000Z", "days_running": 3, "publisher_platforms": [ "FACEBOOK" ], "categories": [ "POLITICAL" ], "body": "Queen Latifah hosts a series of candid conversations honoring the 57th anniversary of the #MarchOnWashington and this new era of the civil rights movement. Change Together features notable civil right...", "title": "Change Together: From the March on Washington to Today", "resolved_body": "Queen Latifah hosts a series of candid conversations honoring the 57th anniversary of the #MarchOnWashington and this new era of the civil rights movement. Change Together features notable civil right...", "resolved_title": "Change Together: From the March on Washington to Today", "display_format": "VIDEO", "creative_type": "video", "is_dynamic_creative": false, "primary_media_url": "https://video.fcph2-1.fna.fbcdn.net/o1/v/t2/f2/m412/AQOhKuKthAVVa0rFEi41ggsiGpIjueM36xj6WP_vqqtBOe-ys_sa5nUBYG9fKBArU14yCLHp-zR-F0aBPcYRtpg.mp4?_nc_cat=107&_nc_oc=AdpHlhQDKfuPaPjrTNrqm4vHUWXl87gS_HUoI...", "image_count": 0, "video_urls": [ "https://video.fcph2-1.fna.fbcdn.net/o1/v/t2/f2/m412/AQOhKuKthAVVa0rFEi41ggsiGpIjueM36xj6WP_vqqtBOe-ys_sa5nUBYG9fKBArU14yCLHp-zR-F0aBPcYRtpg.mp4?_nc_cat=107&_nc_oc=AdpHlhQDKfuPaPjrTNrqm4vHUWXl87gS_HUoI..." ], "video_count": 1, "card_count": 0, "collation_id": "228172181923561", "collation_count": 1, "contains_digital_created_media": false, "contains_sensitive_content": false, "is_political": true, "spend": ">$1M", "spend_lower": 1000000, "currency": "USD", "reach_estimate": ">1M", "reach_lower": 1000000, "impressions": ">1M", "impressions_lower": 1000000, "impressions_index": 39, "byline": "Facebook, Inc.", "disclaimer_label": "PAID_FOR_BY", "detail_enriched": false, "creative_hash": "f6d25256462aa3b2bc44f2cc19a3a01c135f3c58d09e672a0269f17b116f5f64", "search_query": "vote", "search_type": "KEYWORD_UNORDERED", "country_code": "US", "scraped_at": "2026-09-02T06:23:30.872Z", "listingId": "75994c269913f3aa03acf0ec79d5a7ee3931e39594691395f3d1b6670d2172e7", "searchQuery": "vote", "contentQuality": "serp_only", "detailFetched": false, "scrapedAt": "2026-09-02T06:23:30.872Z", "source": "facebook.com", "contentHash": "f6d25256462aa3b2bc44f2cc19a3a01c135f3c58d09e672a0269f17b116f5f64" } ``` ### Incremental fields When incremental mode is on, each record also carries: - `changeType` — one of `NEW`, `UPDATED` or `UNCHANGED`. An ad that stops running stays in the Ad Library with `is_active: false`, so a stopped ad is reported as an `UPDATED` row rather than disappearing. This scraper never reports an ad as expired: an ad missing from a result set means the search moved, not that the ad ended. - `isRepost`, `repostOfId`, `repostDetectedAt` — set when an ad carries a creative you have already seen under a different ad ID, matched on `creative_hash`. Set `skipReposts: true` to drop them from the output. Each saved search remembers the 15,000 most recently seen ads. That is the ceiling of one state record; past it the oldest-seen ads are forgotten, and if one of them shows up again later it is reported as new. Searches that return fewer than that — most keyword and single-advertiser searches — are never affected. ### How to scrape Facebook Ads Library 1. Go to [Facebook Ads Library Scraper](https://apify.com/blackfalcondata/facebook-ads-library-scraper?fpr=1h3gvi) in Apify Console. 2. Enter a search keyword and optional location filter. 3. Set `maxResults` to control how many results you need. 4. Enable `includeDetails` if you need full descriptions. 5. Click **Start** and wait for the run to finish. 6. Export the dataset as JSON, CSV, or Excel. ### Use cases - Track which creatives a competitor is running, and which ones they keep running — `days_running` separates a test from a winner. - Pull every ad an advertiser has live, by pasting their Ad Library URL, and diff it week over week. - Track political and issue-ad spend by advertiser — banded spend, reach and impressions with the "paid for by" disclosure, parsed into sortable numbers. - Measure reach in the EU per ad, broken down by country, age band and gender, without asking the advertiser. - Build a swipe file of ad copy and creative in one niche, deduplicated by `creative_hash` so one creative counts once. - Find the landing pages a category is sending paid traffic to, grouped by `landing_domain`. - Monitor a keyword on a schedule with incremental mode, so each run delivers only the ads that are new. ### How much does it cost to scrape Facebook Ads Library? Facebook Ads Library Scraper uses [pay-per-event](https://docs.apify.com/platform/actors/paid-actors/pay-per-event) pricing. Starting a run is free — you pay only for each result that is actually produced. - **Per ad (primary event):** $0.00005 You are billed only for the events your run actually triggers. Prices below are the Free plan tier. | Event | Price (Free tier) | Charged when | |---|---|---| | Ad (primary) | $0.00005 | One ad, with its creative, copy, landing page, platforms and run duration. | | Add-on: EU reach & advertiser detail | $0.00002 | Charged per ad only when detail enrichment is switched on and the detail record came back: EU reach with the age, gender and country breakdown, plus the advertiser's Instagram handle, followers and page description. | Example costs (primary event only — other events above add cost when they fire): - 10 results: **$0.0005** - 25 results: **$0.00125** - 100 results: **$0.005** - 200 results: **$0.01** - 500 results: **$0.025** #### Example: recurring monitoring savings These examples compare full re-scrapes with incremental runs at different churn rates. Churn is the share of changes that are new or whose tracked content changed since the previous run. Actual churn depends on your query breadth, source activity, and polling frequency — the scenarios below are examples, not predictions. Example setup: 100 changes per run, daily polling (30 runs/month). Costs scale linearly with the number of changes. Numbers below are for the primary **Ad** event. Other events (**Add-on: EU reach & advertiser detail**) are billed separately when they fire. | Churn rate | Full re-scrape run cost | Incremental run cost | Savings vs full re-scrape | Monthly cost after baseline | |---|---:|---:|---:|---:| | 5% — stable niche query | $0.005 | $0.00025 | $0.00475 (95%) | $0.0075 | | 15% — moderate broad query | $0.005 | $0.00075 | $0.00425 (85%) | $0.02 | | 30% — high-volume aggregator | $0.005 | $0.0015 | $0.0035 (70%) | $0.04 | Full re-scrape monthly cost at the same cadence: $0.15. First month with incremental costs $0.01 / $0.03 / $0.05 for the 5% / 15% / 30% scenarios because the first run builds baseline state at full cost before incremental savings apply. Platform usage is included in the per-result fee shown above. ### FAQ #### How many results can I get from Facebook Ads Library? The number of results depends on the search query and available changes on Facebook Ads Library. Use the `maxResults` parameter to control how many results are returned per run. #### Does Facebook Ads Library Scraper support recurring monitoring? Yes. Enable incremental mode to only receive new or changed changes on subsequent runs. This is ideal for scheduled monitoring where you want to track changes over time without re-processing the full dataset. #### Can I integrate Facebook Ads Library Scraper with other apps? Yes. Facebook Ads Library Scraper works with Apify's [integrations](https://apify.com/integrations?fpr=1h3gvi) to connect with tools like Zapier, Make, Google Sheets, Slack, and more. You can also use webhooks to trigger actions when a run completes. #### Can I use Facebook Ads Library Scraper with the Apify API? Yes. You can start runs, manage inputs, and retrieve results programmatically through the [Apify API](https://docs.apify.com/api/v2). Client libraries are available for JavaScript, Python, and other languages. #### Can I use Facebook Ads Library Scraper through an MCP Server? Yes. Apify provides an [MCP Server](https://apify.com/apify/actors-mcp-server?fpr=1h3gvi) that lets AI assistants and agents call this actor directly. Use compact mode, `descriptionMaxLength`, a single `descriptionFormat`, and `excludeEmptyFields` to keep payloads manageable for LLM context windows. #### Is it legal to scrape Facebook Ads Library? This actor extracts publicly available data from Facebook Ads Library. Web scraping of public information is generally considered legal, but you should always review the target site's terms of service and ensure your use case complies with applicable laws and regulations, including GDPR where relevant. #### Your feedback If you have questions, need a feature, or found a bug, please [open an issue](https://apify.com/blackfalcondata/facebook-ads-library-scraper/issues?fpr=1h3gvi) on the actor's page in Apify Console. Your feedback helps us improve. ### You might also like - [Douyin Hot Search Scraper](https://apify.com/blackfalcondata/douyin-scraper?fpr=1h3gvi) — Scrape douyin.com real-time trending boards — hot search, seeding, entertainment, social. - [Meta Ads Library Scraper \[💰$0.05/1k\]](https://apify.com/blackfalcondata/meta-ads-library-scraper?fpr=1h3gvi) — Scrape Meta's Ad Library across Facebook, Instagram, WhatsApp, Threads, Messenger and Audience. - [Pexels Scraper — Photos, Videos & Engagement Data](https://apify.com/blackfalcondata/pexels-scraper?fpr=1h3gvi) — This Pexels scraper extracts photos and videos by search, curated feed, photo ID, user, collection,. - [Pinterest Scraper — Pins, Boards, Profiles & Engagement](https://apify.com/blackfalcondata/pinterest-scraper?fpr=1h3gvi) — Scrape Pinterest pins, boards and profiles by keyword or start URL — images, videos, engagement. - [Reddit Scraper — Posts & Full Comment Threads](https://apify.com/blackfalcondata/reddit-scraper?fpr=1h3gvi) — Scrape Reddit posts with full nested comment threads, or search any subreddit or keyword across. - [Video & Audio Transcriber](https://apify.com/blackfalcondata/video-audio-transcriber?fpr=1h3gvi) — Transcribe any video, audio or podcast URL to text: full transcript with timestamped segments plus. - [YouTube Comment Scraper — Comments, Replies, Likes](https://apify.com/blackfalcondata/youtube-comment-scraper?fpr=1h3gvi) — Scrape YouTube comments and their reply threads from any video, channel, or search query. Each. - [YouTube Scraper $2/1K — Videos, Channels, Comments, Transcripts](https://apify.com/blackfalcondata/youtube-data-scraper?fpr=1h3gvi) — Scrape YouTube videos, channels, comments, and transcripts in one tool — by keyword or by video,. ### Getting started with Apify New to Apify? [Create a free account with $5 credit](https://console.apify.com/sign-up?fpr=1h3gvi) — no credit card required. 1. Sign up — $5 platform credit included 2. Open this actor and configure your input 3. Click **Start** — export results as JSON, CSV, or Excel Need more later? [See Apify pricing](https://apify.com/pricing?fpr=1h3gvi). ### Disclaimer This actor accesses only publicly available data on facebook.com. You are responsible for how you use the extracted data — in particular any personal information such as names, phone numbers, or email addresses — and for complying with Facebook Ads Library's terms of use, applicable data-protection law (including the GDPR where it applies), and the anti-spam rules of your jurisdiction. This actor is not affiliated with, endorsed by, or connected to Facebook Ads Library. ### Search keywords facebook scraper, facebook api, apify facebook, facebook data extraction, facebook ads library scraper, facebook ads library api, apify facebook ads library, facebook ads library data extraction, facebook.com scraper, facebook.com data, facebook.com api, facebook ads library united states, facebook ads library united states scraper, facebook ads library united kingdom, facebook ads library united kingdom scraper, facebook ads library canada, facebook ads library canada scraper, facebook ads library australia, facebook ads library australia scraper, facebook ads library germany, facebook ads library germany scraper, facebook ads library france, facebook ads library france scraper, facebook ads library spain, facebook ads library spain scraper, facebook ads library italy, facebook ads library italy scraper, facebook ads library netherlands, facebook ads library netherlands scraper, facebook ads library sweden, facebook ads library sweden scraper, facebook ads library denmark, facebook ads library denmark scraper, facebook ads library poland, facebook ads library poland scraper, facebook ads library brazil, facebook ads library brazil scraper, facebook ads library mexico, facebook ads library mexico scraper, facebook ads library india. # Actor input Schema ## `query` (type: `string`): Keyword(s) to search the Ad Library for — a brand, product, or phrase that appears in the ad copy or advertiser name. Required if no startUrls provided. ## `startUrls` (type: `array`): Paste raw Ad Library search URLs (https://www.facebook.com/ads/library/?q=...\&country=US or ?view\_all\_page\_id=...). Each URL becomes its own search task; results are merged and deduped by ad archive ID across all URLs. When provided AND parseable, startUrls REPLACE the query field. ## `country` (type: `string`): Ad Library country the ads were delivered in. ALL searches every country. ## `activeStatus` (type: `string`): Only ads currently running, only ads that have stopped, or both. ## `adType` (type: `string`): Meta files some ads in regulated categories. "All ads" covers ordinary commercial advertising. Pick "Political & issue ads" to search the library Meta publishes spend, reach and impression figures for — those columns are filled only there, and come back empty on commercial ads. ## `mediaType` (type: `string`): Restrict to image ads, video ads, or memes. ## `searchType` (type: `string`): Match the search term as separate words, or as an exact phrase. ## `publisherPlatforms` (type: `array`): Only ads shown on these Meta platforms. Leave empty for all of them. ## `contentLanguages` (type: `array`): ISO language codes, e.g. en, de, da. Leave empty for all languages. ## `startDateMin` (type: `string`): Only ads that started running on or after this date (YYYY-MM-DD). ## `startDateMax` (type: `string`): Only ads that started running on or before this date (YYYY-MM-DD). ## `maxResults` (type: `integer`): Maximum total ads to return. The Ad Library is cursor-paginated and hands back about 10 ads per request after the first page, so large numbers mean long runs. ## `includeDetails` (type: `boolean`): Fetches each ad's EU transparency record: total reach in the EU, the age/country/gender breakdown of who saw it, the targeting parameters the advertiser set, plus the advertiser's Instagram handle, follower count and page description. These numbers are not in the ad list — they come from one extra request per ad, so a run with this on takes noticeably longer and costs more. Reach and audience are published by Meta only for ads that target the EU; for other ads those fields come back empty. ## `descriptionMaxLength` (type: `integer`): Truncate description to N chars. 0 = no truncation. ## `compact` (type: `boolean`): Core fields only (for AI-agent/MCP workflows). ## `incrementalMode` (type: `boolean`): Compare against previous run state. ## `stateKey` (type: `string`): Optional. Stable identifier for the tracked search universe. Leave empty to auto-generate from search inputs. ## `skipReposts` (type: `boolean`): When incremental mode is on, drop ads that re-run a creative you have already seen under a different ad ID. Matched on the creative itself (copy, destination and media), not on the ad ID. ## `telegramToken` (type: `string`): Telegram bot token (from @BotFather). Required for Telegram notifications. ## `telegramChatId` (type: `string`): Telegram chat or channel ID (e.g. "-100123456789"). Required when telegramToken is set. ## `discordWebhookUrl` (type: `string`): Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook. ## `slackWebhookUrl` (type: `string`): Slack incoming webhook URL. api.slack.com/messaging/webhooks. ## `notificationLimit` (type: `integer`): Maximum number of listings included in each notification message (1–20). ## `notifyOnlyChanges` (type: `boolean`): When Incremental Mode is on, only send notifications for NEW and UPDATED listings. Has no effect outside incremental mode. ## `whatsappAccessToken` (type: `string`): WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024). ## `whatsappPhoneNumberId` (type: `string`): Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set. ## `whatsappTo` (type: `string`): Recipient phone in E.164 format without + (e.g. "436641234567"). Recipient must have messaged your business number within last 24h. ## `webhookUrl` (type: `string`): Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends. ## `webhookHeaders` (type: `object`): Optional JSON object of custom headers (e.g. {"Authorization":"Bearer ..."}). ## `appConnector` (type: `string`): Optional. Pick a connected app under Settings → API & Integrations to receive your results (including any contact details). Best-effort across MCP connectors as Apify expands its catalog. ## `mcpIssueTeam` (type: `string`): Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one. ## `descriptionFormat` (type: `string`): Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others. ## `excludeEmptyFields` (type: `boolean`): Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards. ## Actor input object example ```json { "query": "nike", "startUrls": [], "country": "US", "activeStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "searchType": "KEYWORD_UNORDERED", "publisherPlatforms": [], "contentLanguages": [], "maxResults": 25, "includeDetails": false, "descriptionMaxLength": 0, "compact": false, "incrementalMode": false, "skipReposts": false, "notificationLimit": 5, "notifyOnlyChanges": false, "descriptionFormat": "all", "excludeEmptyFields": false } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "query": "nike", "activeStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "searchType": "KEYWORD_UNORDERED", "maxResults": 25, "includeDetails": false, "descriptionFormat": "all", "excludeEmptyFields": false }; // Run the Actor and wait for it to finish const run = await client.actor("blackfalcondata/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 = { "query": "nike", "activeStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "searchType": "KEYWORD_UNORDERED", "maxResults": 25, "includeDetails": False, "descriptionFormat": "all", "excludeEmptyFields": False, } # Run the Actor and wait for it to finish run = client.actor("blackfalcondata/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 '{ "query": "nike", "activeStatus": "ALL", "adType": "ALL", "mediaType": "ALL", "searchType": "KEYWORD_UNORDERED", "maxResults": 25, "includeDetails": false, "descriptionFormat": "all", "excludeEmptyFields": false }' | apify call blackfalcondata/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,blackfalcondata/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/av9YBNvSjr6rrPDQ4/builds/y28Nhq9sMNFbV24jO/openapi.json