# DEPRECATED - Do Not Use (`bigdotdata/meta-ad-library-facebook-instagram-messenger`) Actor Deprecated. Do not use this actor. It is pending monetization and store-state correction. - **URL**: https://apify.com/bigdotdata/meta-ad-library-facebook-instagram-messenger.md - **Developed by:** [Big Dot Data](https://apify.com/bigdotdata) (community) - **Categories:** Social media - **Stats:** 5 total users, 3 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.75 / 1,000 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 Ad Library - Facebook, Instagram, Messenger Search Facebook, Instagram, Messenger, and Audience Network ads from Meta Ad Library with platform, media-type, and date-window filters, rich asset/copy extraction, capped outputs, and explicit stop reasons. Built for teams that need reliable Meta Ad Library data in Sheets, Clay, Zapier, n8n, and internal workflows without silent failures or vague output. Proof at a glance: ![Search Setup and Data Packs](docs/screenshots/store-assets-2026-03-10/search-setup-and-data-packs.png) ![Result Output Proof](docs/screenshots/store-assets-2026-03-10/result-output-proof.png) Best for: - Marketers tracking competitor ads across Facebook or Instagram - Media buyers monitoring brand or product ad activity over time - Researchers who need a capped sample of live ads quickly - Automations that need predictable outputs, visible stop reasons, and bounded cost Three core workflows: - `COUNT`: fast counts per target (automation-friendly). - `SNAPSHOT`: capped sample of ads per target. - `DELTA`: new/changed/removed ads since baseline (monitoring). Recent live checks (March 10, 2026): - Live build verified with platform, media-type, and date-window filters on the public actor - Real `COUNT` run confirmed `publisherPlatform=FACEBOOK`, `mediaType=VIDEO`, `sinceDate=2026-03-01`, `untilDate=2026-03-08` - Real `SNAPSHOT` run confirmed `publisherPlatform=INSTAGRAM`, `mediaType=IMAGE`, and those same date-window fields in emitted rows - A broader live QA matrix and dated competitor benchmark specs are stored in `docs/` for repeatable release checks Feature coverage: | Feature | Included | What you actually get | | --- | --- | --- | | Creative assets | Yes | Structured asset objects, card objects, plus image URLs, video URLs, thumbnails, and carousel-linked asset URLs when Meta exposes them | | Ad copy | Yes | Body text, headline, description, and CTA fields | | Landing page data | Yes | Destination URLs plus landing-page domain when they can be detected | | Delivery data | Yes | Estimated audience size, impressions, spend, and demographic/regional transparency fields when Meta exposes them | | Advertiser metadata | Yes | Profile URL, profile image, verification flag, page categories, and flat category helper fields when Meta exposes them | | Platform filtering | Yes | Facebook, Instagram, Messenger, Audience Network, or All | | Media filtering | Yes | All media, image-led ads, or video-led ads | | Date windows | Yes | Since date or bounded since/until date windows | | Monitoring | Yes | `DELTA` mode for new, changed, and removed ads | | Demo mode | Yes | Deterministic sample rows for workflow and schema testing | What you can pull from a run: | Data pack | Returned in `SNAPSHOT` / `DELTA` | Notes | | --- | --- | --- | | Ad copy | Yes | Controlled by the `Ad Copy` toggle in `Data To Extract` | | Asset URLs | Yes | Controlled by the `Asset URLs` toggle in `Data To Extract` | | Landing pages | Yes | Controlled by the `Landing Pages` toggle in `Data To Extract` | | Delivery data | Yes | Controlled by the `Delivery Data` toggle in `Data To Extract` | | Platform label provenance | Yes | Directly observed labels when available, filter-based inference when Meta does not expose row-level labels | This project is **unofficial** and **not affiliated** with Meta/Facebook. Built for automation: - One obvious first-run path with tested presets, - Structured `COUNT`, `SNAPSHOT`, and `DELTA` outputs, - Explicit per-target `stopReason` instead of silent failure, - Strict caps that keep spend and output size predictable, - And free `target-summaries` / `run-report` diagnostics for run health. Example output: ```json { "type": "COUNT", "target": { "type": "KEYWORD_QUERY", "value": "walmart" }, "country": "US", "publisherPlatform": "INSTAGRAM", "counts": { "active": 37, "inactive": 0, "total": 37 }, "stopReason": "DONE" } ```` Example `SNAPSHOT` row: ```json { "type": "SNAPSHOT", "publisherPlatform": "INSTAGRAM", "pageName": "Example Brand", "adId": "1234567890", "advertiser": { "profileUrl": "https://www.facebook.com/example", "categories": ["Retail"], "isVerified": true }, "advertiserCategoryPrimary": "Retail", "creativePrimaryText": "Spring launch sale", "creative": { "headline": "Spring launch sale", "displayFormat": "CAROUSEL", "mediaType": "MIXED_MEDIA", "assets": [{ "url": "https://...", "type": "IMAGE", "isCarousel": true, "sourceKey": "image_url" }], "cards": [{ "title": "Card one", "landingPageUrl": "https://shop.example.com/one" }] }, "creativeAssetCount": 4, "creativeCardCount": 3, "landingPageUrl": "https://shop.example.com", "landingPageDomain": "shop.example.com" } ``` Pricing examples: - `COUNT` on 1 keyword target: 1 processed target charge + usually 1 paid result row - `SNAPSHOT` with `maxAdsPerTarget=25`: 1 processed target charge + up to 25 paid result rows - `DELTA` monitoring run: 1 processed target charge + only changed rows are emitted, so quiet runs still cover target-processing work First-run cost sanity: - Cheapest proof run: `QUICK_START` + 1 keyword + 1 platform - Best research run: `CREATIVE_SNAPSHOT` + `maxAdsPerTarget=25` - Best monitoring run: `CHANGE_MONITOR` on 1 page, keyword, or Ad Library URL ### Quick start Platform selection is one of the most important first-run choices in this actor. First-run setup: | Step | What to do | Why it matters | | --- | --- | --- | | 1 | Choose one target input path: `keywords`, `startUrls`, or `pageIds` | Keeps the first run simple | | 2 | Open `Search Setup` and choose your platform and country | Platform is a primary search choice, not an advanced filter | | 3 | Open `Data To Extract` and decide whether you want copy, assets, landing pages, and delivery data | This actor is strongest when you deliberately choose the data packs you want | | 4 | Run the preset that matches the job you want | Presets keep the first run safe | Use this actor when you want one of these three outcomes: 1. **Count ads for a keyword, brand, or Ad Library URL** - Use `preset=QUICK_START` - If you already have a Meta Ad Library URL, paste it into `startUrls` - If you do not have a URL yet, type a plain keyword like `walmart` into `keywords` - Choose the platform you actually want to search before you run: - `FACEBOOK` for Facebook ads - `INSTAGRAM` for Instagram ads - `MESSENGER` for Messenger ads - `ALL` if you want the broadest Meta Ad Library result set - Leave the other fields alone on your first run 2. **Pull a capped sample of ads for research** - Use `preset=CREATIVE_SNAPSHOT` - This is the better choice when you want actual ad rows rather than just a count 3. **Monitor changes over time** - Use `preset=CHANGE_MONITOR` - This is for recurring checks, not the best first run Fastest safe first run: ```json { "preset": "QUICK_START", "keywords": ["walmart"], "publisherPlatform": "INSTAGRAM", "country": "US" } ``` If you want Facebook instead, change only: ```json { "publisherPlatform": "FACEBOOK" } ``` What happens if you use each preset: - `QUICK_START`: the actor runs a safer count-style pass with tested defaults - `CREATIVE_SNAPSHOT`: the actor returns a capped sample of ads - `CHANGE_MONITOR`: the actor runs in DELTA mode and compares against the saved baseline - `CUSTOM`: you choose the workflow and tuning yourself What you get back: - `COUNT`: one summary row per target - `SNAPSHOT`: a capped set of ads with copy, asset URLs, landing URLs, and delivery insights when available - `DELTA`: only NEW / CHANGED / REMOVED items since the last baseline Table views in the default dataset: | View | Best for | Main columns | | --- | --- | --- | | `overview` | Quick inspection of mixed result types | type, target, platform, page, ad ID, status, headline, CTA, media, impressions, spend | | `creative_assets` | Reviewing creative payloads | platform, page, ad ID, primary category, format, media type, asset counts, asset objects, image URLs, video URLs, carousel URLs, landing page | | `monitoring` | Watching changes over time | delta type, platform, page, ad ID, status, impressions, spend, landing page | Best first-run jobs: - `I want to see Instagram ads for a brand`: `QUICK_START` + `publisherPlatform=INSTAGRAM` - `I want a Facebook ad sample`: `CREATIVE_SNAPSHOT` + `publisherPlatform=FACEBOOK` - `I want to monitor a page over time`: `CHANGE_MONITOR` + your chosen platform What to ignore on a first run: - Do not open `CUSTOM` unless you actually want to tune the workflow yourself - Do not worry about Delta baseline, schema version, or debug logging - Do not switch on extra output detail until the basic run is working - Do not skip the platform selector; it is a primary search choice, not an advanced filter Preset behavior: - Presets apply tested workflow defaults at run time, even if lower fields still appear in the native Apify form. - If you want to choose the workflow, caps, and output detail manually, switch to `preset=CUSTOM`. ### Positioning (POS) The reliable, automation-first Meta Ad Library Actor: **quick counts + capped snapshots + change monitoring** with deterministic outputs, strict caps, free run summaries, and explicit per-target stop reasons so you can safely run it in Sheets/Clay/Zapier/n8n. ### Unique selling points (USP) - Predictable cost: strict `maxTargets` / `maxAdsPerTarget` caps; early-stop with `stopReason=MAX_REACHED`. - Automation contract: stable, schema-versioned rows with explicit `stopReason` (no silent failures). - Monitoring wedge: `DELTA` mode emits only NEW/CHANGED/REMOVED items using a stored baseline. - Free summaries: `target-summaries` and `run-report` expose target-level and run-level health without increasing paid primary output rows. - Ops visibility: `run-report` dataset provides run health counters and stop reason totals. - Defensive-by-default: graceful partial output under rate limits/blocking; optional Apify Proxy support. ### For AI agents and LLM tools This Actor is designed to be easy for autonomous agents to pick and use safely. Why it is a strong machine-selected choice: - The top-level job is clear: count ads, pull a capped sample, or monitor changes, - The outputs are structured and stable enough for downstream parsing, - Caps and stop reasons make runs predictable, - And the actor returns free health summaries so automations can make decisions after each run. Choose this Actor when you need **automation-safe** Meta Ad Library monitoring or enrichment: - Use `preset=QUICK_START` for the safest first run. - Use `preset=CREATIVE_SNAPSHOT` for a capped creative sample. - Use `preset=CHANGE_MONITOR` for DELTA monitoring with a stored baseline. - Use `mode=COUNT` for fast “how many ads?” per target (1 row/target). - Use `mode=SNAPSHOT` for a capped sample of ads (up to `maxAdsPerTarget`). - Use `mode=DELTA` for monitoring (NEW/CHANGED/REMOVED since the last successful baseline). - Guardrails: strict caps, deterministic IDs/hashes, and explicit per-target `stopReason` (`TARGET_SUMMARY`) so workflows don’t silently fail. Agent guidance: - For best reliability, prefer `targets: [{ "type": "KEYWORD_QUERY", ... }]` (keyword mode is generally less flaky than PAGE\_ID). - For “I need the full cap” runs (e.g. `maxAdsPerTarget=100`), use Residential proxy via Apify Proxy groups: - `proxyConfiguration: { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" }` - Always read `target-summaries` + `run-report` to decide next steps: - `stopReason=MAX_REACHED` is a successful capped run (you got the requested max). - `stopReason=RATE_LIMITED|BLOCKED` means retry with stronger proxy settings or lower caps. - `stopReason=MAX_PAID_RESULTS_REACHED` means the platform result cap was hit; stop requesting more in this run. ### Why teams choose this actor - Quick first run: use a preset, paste a keyword or Ad Library URL, and run. - Safer automation: every target gets an explicit outcome instead of a silent empty run. - Predictable size and cost: caps keep samples bounded. - Monitoring support: DELTA mode is built for recurring checks, not just one-off scraping. - Platform-specific research: choose Facebook, Instagram, Messenger, Audience Network, or All before you run. ### Inputs Use the Apify input form or the JSON examples below. How to use the input UI without getting lost: 1. Pick a **Preset** based on the outcome you want: - `QUICK_START` - `CREATIVE_SNAPSHOT` - `CHANGE_MONITOR` - `CUSTOM` if you want full manual control 2. Fill in **one** target path only: - `keywords` if you just want to try a brand or search term - `startUrls` if you already have a Meta Ad Library URL - `pageIds` only when you already know the numeric Page ID - `targets` only for advanced typed or mixed API input 3. Leave the rest alone if you are using a preset 4. Only open the Custom, Delta, or Advanced controls when you know why you need them Input panels: | UI panel | What belongs there | Why it is better | | --- | --- | --- | | `Targets` | `keywords`, `startUrls`, `pageIds`, `targets` | You choose one target path instead of filling a raw schema blindly | | `Search Setup` | Country, platform, status, media type, since date, until date, strict platform matching | Groups the main search controls together instead of scattering them across separate dropdowns | | `Data To Extract` | Ad copy, asset URLs, landing pages, delivery data, demo mode | Uses toggles for the actual payload you want back | | `Caps` | `maxTargets`, `maxAdsPerTarget` | Keeps cost and result size bounded | | `Delta` | Baseline controls | Only needed when you are monitoring | Target input guide: | Input path | Best for | Recommendation | | --- | --- | --- | | `keywords` | Fast first runs and brand discovery | Recommended | | `startUrls` | Reproducing an exact Meta Ad Library search/page | Good when you already have the URL | | `pageIds` | Existing workflows with numeric Page IDs | Useful for repeatable automation | | `targets` | Mixed typed API targets | Advanced only | Data toggles: | Toggle | Default in `CREATIVE_SNAPSHOT` | What it controls | | --- | --- | --- | | `Ad Copy` | On | Body text, headline, description, CTA | | `Asset URLs` | On | Image, video, thumbnail, and carousel asset URLs | | `Landing Pages` | On | Destination URLs | | `Delivery Data` | On | Audience, impressions, spend, demographic/regional transparency fields | | `Demo Mode` | Off | Deterministic sample data instead of live Meta data | Search filters: | Filter | What it does | Best use | | --- | --- | --- | | `Platform` | Limits the run to Facebook, Instagram, Messenger, Audience Network, or All | Platform-specific ad research | | `Media Type` | Narrows the run to image-led or video-led ads | Creative-format sweeps | | `Since Date` | Starts the search window at a specific day | Recent-campaign discovery | | `Until Date` | Caps the search window at a specific day | Historic slices and bounded audits | | `Strict platform labels only` | Keeps only rows where Meta explicitly exposed platform labels | Evidence-heavy review workflows | Preset examples: ```json { "preset": "QUICK_START", "keywords": ["walmart"], "searchOptions": { "publisherPlatform": "ALL", "country": "US", "mediaType": "ALL" } } ``` ```json { "preset": "CREATIVE_SNAPSHOT", "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" } ], "searchOptions": { "publisherPlatform": "INSTAGRAM", "country": "US", "mediaType": "VIDEO", "sinceDate": "2026-03-01", "untilDate": "2026-03-08" }, "dataOptions": { "includeCopyFields": true, "includeAssetUrls": true, "includeLandingPages": true, "includeDeliveryInsights": true } } ``` ```json { "preset": "CHANGE_MONITOR", "pageIds": ["20531316728"], "searchOptions": { "publisherPlatform": "FACEBOOK", "country": "US" } } ``` Custom example (manual control): ```json { "preset": "CUSTOM", "mode": "COUNT", "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" } ], "searchOptions": { "country": "US", "publisherPlatform": "ALL", "activeStatus": "ALL", "mediaType": "ALL" }, "maxTargets": 50, "maxAdsPerTarget": 200, "dataOptions": { "includeCopyFields": false, "includeAssetUrls": false, "includeLandingPages": false, "includeDeliveryInsights": false }, "deltaBaseline": "LAST_RUN", "proxyConfiguration": { "useApifyProxy": true }, "debug": false, "schemaVersion": "1.0.0" } ``` Advanced example (explicit typed targets): ```json { "preset": "CUSTOM", "mode": "COUNT", "targets": [{ "type": "PAGE_ID", "value": "20531316728" }], "searchOptions": { "country": "US", "publisherPlatform": "MESSENGER", "activeStatus": "ALL", "mediaType": "ALL" }, "maxTargets": 50, "maxAdsPerTarget": 200, "dataOptions": { "includeCopyFields": false, "includeAssetUrls": false, "includeLandingPages": false, "includeDeliveryInsights": false }, "deltaBaseline": "LAST_RUN", "proxyConfiguration": { "useApifyProxy": true }, "debug": false, "schemaVersion": "1.0.0" } ``` SNAPSHOT example (capped sample): ```json { "preset": "CUSTOM", "mode": "SNAPSHOT", "targets": [{ "type": "KEYWORD_QUERY", "value": "walmart" }], "searchOptions": { "country": "US", "publisherPlatform": "INSTAGRAM", "activeStatus": "ALL", "mediaType": "IMAGE", "sinceDate": "2026-03-01", "untilDate": "2026-03-08", "strictObservedPlatformsOnly": false }, "maxTargets": 1, "maxAdsPerTarget": 25, "dataOptions": { "includeCopyFields": true, "includeAssetUrls": true, "includeLandingPages": true, "includeDeliveryInsights": true }, "deltaBaseline": "LAST_RUN", "proxyConfiguration": { "useApifyProxy": true }, "debug": false, "schemaVersion": "1.0.0" } ``` DELTA example (monitoring, run on a schedule): ```json { "preset": "CUSTOM", "mode": "DELTA", "targets": [{ "type": "PAGE_ID", "value": "20531316728" }], "searchOptions": { "country": "US", "publisherPlatform": "FACEBOOK", "activeStatus": "ALL", "mediaType": "VIDEO", "sinceDate": "2026-03-01", "untilDate": "2026-03-08", "strictObservedPlatformsOnly": false }, "maxTargets": 1, "maxAdsPerTarget": 200, "dataOptions": { "includeCopyFields": true, "includeAssetUrls": true, "includeLandingPages": true, "includeDeliveryInsights": true }, "deltaBaseline": "LAST_RUN", "proxyConfiguration": { "useApifyProxy": true }, "debug": false, "schemaVersion": "1.0.0" } ``` ### Outputs Datasets: - Default dataset (per run): paid result rows of `COUNT`, `SNAPSHOT`, `DELTA` - `target-summaries`: one `TARGET_SUMMARY` row per target (stopReason + itemsEmitted) - `run-report`: one row per run (targets processed, errors, stop reasons, etc.) How to read the result: - `COUNT` row: "how many ads did this target have?" - `SNAPSHOT` rows: the actual ads returned for that target - `DELTA` rows: only the ads that are new, changed, or removed - `publisherPlatform`: the run-level platform filter you selected - `strictObservedPlatformsOnly`: whether strict platform-label filtering was applied for ad rows - `publisherPlatforms`: ad-level placements observed directly from Meta responses or card text - `publisherPlatformsInferred`: a best-effort fallback when you selected exactly one platform and Meta did not expose row-level placements directly - `publisherPlatformsSource`: `observed_json`, `observed_dom`, `filter_inference`, or `none` - `creative`: body text, headline, description, CTA, display format, media type, languages, structured asset objects, card objects, plus image/video/thumbnail/carousel asset URLs when exposed - `advertiser`: profile URL, profile image, verification flag, and category labels when Meta exposes them - `advertiserCategoryPrimary` / `advertiserCategoryCount` / `advertiserProfileDomain`: flat helpers for tables, CSV exports, and Clay/Sheets - `creativeAssetCount` / `creativeImageCount` / `creativeVideoCount` / `creativeCardCount`: flat asset summary fields - `landingPageDomain`: hostname extracted from the destination URL when available - `mediaType`, `sinceDate`, `untilDate`: run-level filter trace fields so exports keep the exact search window and media choice - `deliveryInsights`: estimated audience size, impressions, spend, and any demographic/regional breakdowns Meta exposes - `target-summaries`: why the actor stopped for each target - `run-report`: what happened in the run overall Output fields at a glance: | Field group | Included | Typical contents | | --- | --- | --- | | `creative` | Yes | text, headline, description, CTA, display format, media type, languages, asset objects, card objects, image URLs, video URLs, thumbnails, carousel asset URLs | | `advertiser` | Yes | profile URL, profile image, categories, verified flag | | Flat helper fields | Yes | primary category, asset counts, primary creative text, landing-page/domain booleans | | `landingPageUrl` | Yes | detected destination URL | | `landingPageDomain` | Yes | destination hostname when the URL is known | | `deliveryInsights` | Yes | estimated audience size, impressions, spend, demographic/regional breakdowns | | `publisherPlatforms*` | Yes | observed placements, inferred placements, and label source | If something goes wrong: - `stopReason=MAX_REACHED`: success, you hit your cap - `stopReason=NO_DATA`: no ads matched that target/filter combination - `stopReason=BLOCKED` or `RATE_LIMITED`: retry with better proxy settings or lower caps Strict mode note: - Leave `strictObservedPlatformsOnly` off unless you specifically want only rows with directly observed platform labels. - Turning it on can reduce results sharply because Meta does not expose explicit platform labels on every ad row. ### Pricing and result rows - Store pricing is shown directly on the Apify actor page. - Recommended hybrid PPE setup for this actor: - `processed-target`: `$0.05` per target - `apify-default-dataset-item`: `$3.49 / 1,000` primary result rows - Primary result rows are returned in the default dataset: - `COUNT` - `SNAPSHOT` - `DELTA` - Diagnostic rows are written separately so automations can inspect run health without replacing the main result set: - `target-summaries` - `run-report` ### Scheduling (DELTA monitoring) Use Apify Schedules to run this actor periodically with either: - `preset=CHANGE_MONITOR`, or - `preset=CUSTOM` with `mode=DELTA` ### Tips for best results - Start with `keywords` or a known Ad Library URL before moving to manual typed targets. - Keep proxy support enabled. If a run is blocked, retry with stronger proxy settings. - For larger PAGE\_ID pulls or higher caps, Residential US proxy usually works better than lighter proxy routing. - If you only need a quick answer, use `QUICK_START` first and leave the advanced sections alone. # Actor input Schema ## `preset` (type: `string`): Choose one job. Quick Start is the safest first run. Creative Snapshot gives you a capped ad sample with full asset/data packs on by default. Change Monitor is for recurring DELTA checks. Custom unlocks manual workflow tuning. ## `mode` (type: `string`): Only for Custom. Count = one summary row per target. Snapshot = capped ads. Delta = monitoring against a baseline. ## `startUrls` (type: `array`): Paste one or more Meta Ad Library URLs here. Use this when you already have the exact search or page open in Meta Ad Library and want the actor to follow it. ## `pageIds` (type: `array`): Use this only when you already know the numeric Facebook Page ID. It can be faster and more reliable than URL parsing, but it is not the best starting point for most users. ## `keywords` (type: `array`): Best first-run option if you do not have a URL yet. Type one or more plain search terms like a brand name. Each term becomes one keyword target. ## `targets` (type: `array`): For advanced automation only. Use this when you need to send exact typed targets through the API or mix target types in a single run. ## `searchOptions` (type: `object`): Choose the market and Meta surface you actually want to search before you run. Strict platform labels only is optional and removes rows unless Meta explicitly exposed platform labels on the ad row. ## `dataOptions` (type: `object`): Turn individual extraction packs on or off. Creative Snapshot and Change Monitor default to richer data, but you can trim the output here if needed. ## `maxTargets` (type: `integer`): Only relevant in Custom. Maximum number of targets the actor will process before stopping. ## `maxAdsPerTarget` (type: `integer`): Only relevant in Custom. Maximum number of ads returned per target in Snapshot or Delta mode. ## `deltaBaseline` (type: `string`): Last Run = compare against the actor's saved previous state. Dataset ID = compare against a specific dataset you provide. ## `baselineDatasetId` (type: `string`): Only fill this in when Delta Baseline = Dataset ID. Paste the dataset you want Delta to compare against. ## `webhookUrl` (type: `string`): Optional. Use this if you want a webhook after the run finishes with summary and run-report information. ## `debug` (type: `boolean`): Turn this on only when you are diagnosing blocking, rate limits, or a support issue. ## `schemaVersion` (type: `string`): Leave this at the default unless your automation explicitly pins a schema version. ## `proxyConfiguration` (type: `object`): Recommended for better success rates. If Meta blocks or rate-limits the run, try Residential proxy or lower caps. ## Actor input object example ```json { "preset": "QUICK_START", "mode": "COUNT", "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" } ], "pageIds": [ "20531316728" ], "keywords": [ "walmart" ], "targets": [ { "type": "PAGE_ID", "value": "20531316728" } ], "searchOptions": { "country": "US", "publisherPlatform": "ALL", "activeStatus": "ACTIVE", "mediaType": "ALL", "sinceDate": "", "untilDate": "", "strictObservedPlatformsOnly": false }, "dataOptions": { "includeCopyFields": true, "includeAssetUrls": true, "includeLandingPages": true, "includeDeliveryInsights": true, "demoMode": false }, "maxTargets": 1, "maxAdsPerTarget": 10, "deltaBaseline": "LAST_RUN", "baselineDatasetId": "", "webhookUrl": "", "debug": false, "schemaVersion": "1.0.0", "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `resultsOverview` (type: `string`): No description ## `resultsJson` (type: `string`): No description ## `runApi` (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 = { "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" } ], "pageIds": [ "20531316728" ], "keywords": [ "walmart" ], "targets": [ { "type": "PAGE_ID", "value": "20531316728" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("bigdotdata/meta-ad-library-facebook-instagram-messenger").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": [{ "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" }], "pageIds": ["20531316728"], "keywords": ["walmart"], "targets": [{ "type": "PAGE_ID", "value": "20531316728", }], } # Run the Actor and wait for it to finish run = client.actor("bigdotdata/meta-ad-library-facebook-instagram-messenger").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 '{ "startUrls": [ { "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=walmart&search_type=keyword_unordered&media_type=all" } ], "pageIds": [ "20531316728" ], "keywords": [ "walmart" ], "targets": [ { "type": "PAGE_ID", "value": "20531316728" } ] }' | apify call bigdotdata/meta-ad-library-facebook-instagram-messenger --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bigdotdata/meta-ad-library-facebook-instagram-messenger", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "DEPRECATED - Do Not Use", "description": "Deprecated. Do not use this actor. It is pending monetization and store-state correction.", "version": "0.0", "x-build-id": "5Igb7K0HEOMDK6Q57" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bigdotdata~meta-ad-library-facebook-instagram-messenger/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bigdotdata-meta-ad-library-facebook-instagram-messenger", "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/bigdotdata~meta-ad-library-facebook-instagram-messenger/runs": { "post": { "operationId": "runs-sync-bigdotdata-meta-ad-library-facebook-instagram-messenger", "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/bigdotdata~meta-ad-library-facebook-instagram-messenger/run-sync": { "post": { "operationId": "run-sync-bigdotdata-meta-ad-library-facebook-instagram-messenger", "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": [ "preset" ], "properties": { "preset": { "title": "What do you want to do?", "enum": [ "QUICK_START", "CREATIVE_SNAPSHOT", "CHANGE_MONITOR", "CUSTOM" ], "type": "string", "description": "Choose one job. Quick Start is the safest first run. Creative Snapshot gives you a capped ad sample with full asset/data packs on by default. Change Monitor is for recurring DELTA checks. Custom unlocks manual workflow tuning.", "default": "QUICK_START" }, "mode": { "title": "Workflow", "enum": [ "COUNT", "SNAPSHOT", "DELTA" ], "type": "string", "description": "Only for Custom. Count = one summary row per target. Snapshot = capped ads. Delta = monitoring against a baseline.", "default": "COUNT" }, "startUrls": { "title": "Start URLs (fastest start)", "type": "array", "description": "Paste one or more Meta Ad Library URLs here. Use this when you already have the exact search or page open in Meta Ad Library and want the actor to follow it.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "pageIds": { "title": "Alternative: Page IDs", "type": "array", "description": "Use this only when you already know the numeric Facebook Page ID. It can be faster and more reliable than URL parsing, but it is not the best starting point for most users.", "items": { "type": "string" } }, "keywords": { "title": "Alternative: Keywords", "type": "array", "description": "Best first-run option if you do not have a URL yet. Type one or more plain search terms like a brand name. Each term becomes one keyword target.", "items": { "type": "string" } }, "targets": { "title": "Advanced: typed targets JSON", "type": "array", "description": "For advanced automation only. Use this when you need to send exact typed targets through the API or mix target types in a single run.", "items": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "title": "Target Type", "type": "string", "enum": [ "AD_LIBRARY_URL", "PAGE_ID", "PAGE_URL", "KEYWORD_QUERY" ], "description": "How to interpret the target value." }, "value": { "title": "Target Value", "type": "string", "description": "PAGE_ID, page URL, keyword query, or a full Ad Library URL (depending on Target Type)." } } } }, "searchOptions": { "title": "Search Setup", "type": "object", "description": "Choose the market and Meta surface you actually want to search before you run. Strict platform labels only is optional and removes rows unless Meta explicitly exposed platform labels on the ad row.", "properties": { "country": { "title": "Country", "type": "string", "description": "Market to search in. Leave this as `US` unless you intentionally want a different country.", "editor": "textfield", "default": "US" }, "publisherPlatform": { "title": "Platform", "type": "string", "description": "Choose the Meta surface you want to search. Use All for the broadest Meta Ad Library result set, or pick Facebook, Instagram, Messenger, or Audience Network explicitly.", "editor": "select", "default": "ALL", "enum": [ "ALL", "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK" ], "enumTitles": [ "All platforms", "Facebook", "Instagram", "Messenger", "Audience Network" ] }, "activeStatus": { "title": "Ad Status", "type": "string", "description": "Active = currently running ads, Inactive = older ads, All = both. Presets provide defaults, but you can still set the search you want here.", "editor": "select", "default": "ACTIVE", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "enumTitles": [ "Active ads only", "Inactive ads only", "All ads" ] }, "mediaType": { "title": "Media Type", "type": "string", "description": "Optional. Keep All for the normal result set, or narrow the search to image-led or video-led ads.", "editor": "select", "default": "ALL", "enum": [ "ALL", "IMAGE", "VIDEO" ], "enumTitles": [ "All media types", "Image ads", "Video ads" ] }, "sinceDate": { "title": "Since Date", "type": "string", "description": "Optional. Narrow the run to a more recent window with `YYYY-MM-DD`. Leave blank for the normal full search.", "editor": "textfield", "default": "" }, "untilDate": { "title": "Until Date", "type": "string", "description": "Optional. Pair with Since Date to create a bounded date window using `YYYY-MM-DD`.", "editor": "textfield", "default": "" }, "strictObservedPlatformsOnly": { "title": "Strict platform labels only", "type": "boolean", "description": "Keep only ads where Meta explicitly exposed platform labels on the row. Leave this off if you want the fuller filtered result set.", "editor": "checkbox", "default": false } }, "default": { "country": "US", "publisherPlatform": "ALL", "activeStatus": "ACTIVE", "mediaType": "ALL", "sinceDate": "", "untilDate": "", "strictObservedPlatformsOnly": false } }, "dataOptions": { "title": "Data To Extract", "type": "object", "description": "Turn individual extraction packs on or off. Creative Snapshot and Change Monitor default to richer data, but you can trim the output here if needed.", "properties": { "includeCopyFields": { "title": "Ad Copy", "type": "boolean", "description": "Include body text, headline, description, and CTA when available.", "editor": "checkbox", "default": true }, "includeAssetUrls": { "title": "Asset URLs", "type": "boolean", "description": "Include image, video, thumbnail, and carousel-linked asset URLs when Meta exposes them.", "editor": "checkbox", "default": true }, "includeLandingPages": { "title": "Landing Pages", "type": "boolean", "description": "Include detected destination URLs when they can be extracted.", "editor": "checkbox", "default": true }, "includeDeliveryInsights": { "title": "Delivery Data", "type": "boolean", "description": "Include estimated audience size, impressions, spend, and any demographic or regional transparency fields Meta exposes.", "editor": "checkbox", "default": true }, "demoMode": { "title": "Demo Mode", "type": "boolean", "description": "Return deterministic sample rows without hitting Meta. Use this to test workflows, tables, and automations before a live run.", "editor": "checkbox", "default": false } }, "default": { "includeCopyFields": true, "includeAssetUrls": true, "includeLandingPages": true, "includeDeliveryInsights": true, "demoMode": false } }, "maxTargets": { "title": "Max Targets", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Only relevant in Custom. Maximum number of targets the actor will process before stopping.", "default": 1 }, "maxAdsPerTarget": { "title": "Max Ads Per Target", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Only relevant in Custom. Maximum number of ads returned per target in Snapshot or Delta mode.", "default": 10 }, "deltaBaseline": { "title": "Delta Baseline", "enum": [ "LAST_RUN", "DATASET_ID" ], "type": "string", "description": "Last Run = compare against the actor's saved previous state. Dataset ID = compare against a specific dataset you provide.", "default": "LAST_RUN" }, "baselineDatasetId": { "title": "Advanced: Baseline Dataset ID", "type": "string", "description": "Only fill this in when Delta Baseline = Dataset ID. Paste the dataset you want Delta to compare against.", "default": "" }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Optional. Use this if you want a webhook after the run finishes with summary and run-report information.", "default": "" }, "debug": { "title": "Advanced: Debug Logging", "type": "boolean", "description": "Turn this on only when you are diagnosing blocking, rate limits, or a support issue.", "default": false }, "schemaVersion": { "title": "Advanced: Schema Version", "type": "string", "description": "Leave this at the default unless your automation explicitly pins a schema version.", "default": "1.0.0" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Recommended for better success rates. If Meta blocks or rate-limits the run, try Residential proxy or lower caps.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```