# Facebook Ads Library Scraper (`nice_dev/facebook-ads-library-scraper`) Actor

Scrape the Meta Ad Library (Facebook, Instagram, Messenger, Threads) by keyword, advertiser, ad ID or URL in any country: ad text, media, links, dates, platforms, spend and EU audience. No login. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/nice_dev/facebook-ads-library-scraper.md
- **Developed by:** [Nice Dev](https://apify.com/nice_dev) (community)
- **Categories:** Social media, Marketing, MCP servers
- **Features:** Limited permissions
- **Stats:** 6 total users, 2 monthly users, 98.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.04 / 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.
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

### 📣 What is Facebook Ads Library Scraper?

**Facebook Ads Library Scraper** extracts **ads from the [Meta Ad Library](https://www.facebook.com/ads/library/)** — the ads that run on **Facebook, Instagram, Messenger, Audience Network and Threads**: **ad text, headline, images and videos, link and button, start and end dates, days running, platforms, advertiser page, and for political and issue ads the spend, impressions and audience**. Search by keyword, by advertiser (name, page link or page ID), by ad ID or with any Ad Library URL, in one country or many. It works as a **Facebook Ad Library API alternative**: no developer account or access token, every kind of ad, and you can run it on a schedule, call it from your code, or plug it into Make, Zapier or n8n — for competitor ad research (ad spy), creative inspiration, market sizing or political ad monitoring.

Type a **keyword** (`running shoes`) or an **advertiser** (`Nike`), pick a **country**, click **Start**, and download the ads in JSON, CSV or Excel. No Facebook account, no cookies, nothing to set up: in our tests, **one search returned 1,000 ads in under 5 minutes**. Extra data (EU audience and payer, advertiser profile, page owner, all versions, final landing page, contacts, saved media) are options, off by default, that you pay only when you tick them.

### 📋 What data can you extract from the Meta Ad Library?

One item per ad, 99 fields:

| Category                                                | What you get                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 🏷️ **Ad**                                               | Ad Library ID, link to the ad, running or stopped, ad category (political, housing, employment…), group of identical ads and how many versions it has                                                                                                                                      |
| 🏢 **Advertiser**                                       | page name, page ID, page link, profile picture, page categories, page likes, deleted page, "Paid for by" line — `Lost Dutchman Leather Goods`                                                                                                                                              |
| 📝 **Creative**                                         | headline, ad text, caption, link description, button (`Shop now`), format (image, video, carousel, catalog, dynamic), every card of a carousel or catalog ad, dynamic texts, branded-content partner, the full creative object as Meta returns it                                          |
| 🖼️ **Images and videos**                                | every image and video link (HD and SD, preview image); the text written in the images (option)                                                                                                                                                                                                                                      |
| 🔗 **Link**                                             | the URL the ad points to, its domain, its UTM tracking parameters — `lostdutchmanleather.com`                                                                                                                                                                                              |
| 🕒 **Dates**                                            | start date, end date, days running (`826`), total active time                                                                                                                                                                                                                              |
| 📱 **Platforms and countries**                          | Facebook, Instagram, Messenger, Audience Network, Threads; the countries the ad targeted or reached                                                                                                                                                                                        |
| 💰 **Spend and reach** (political and issue ads)        | amount spent as Meta prints it (`$600K - $700K`) with its lower and upper bounds, currency, impressions range (`>1M`), estimated audience size                                                                                                                                             |
| 🛡️ **Transparency labels**                              | sensitive content, digitally created or AI-altered media, state-controlled media, EU transparency eligibility, reports                                                                                                                                                                     |
| 🔎 **Search**                                           | keyword, country, advertiser and URL of the search that found the ad, and how many ads the Ad Library has for that search                                                                                                                                                                  |
| 🇪🇺 **Ad details** (option)                              | who paid and who benefits, and for ads shown in the EU, UK or Brazil the audience Meta publishes: total EU reach, targeted locations, gender and ages, reach by country, age and gender                                                                                                    |
| 👤 **Advertiser profile, owner and audience** (options) | Instagram account and followers, verification badges, total spend on political ads; the confirmed page owner (name, address, phone when published), page creation date, name changes, countries of the page managers; the advertiser's ad count, spend and targeting over 7, 30 or 90 days |
| 🛬 **Landing page and contacts** (options)              | final landing URL after redirects, page title, product name, price, brand, availability and rating; e-mails, phone numbers, social links and shop platform (Shopify, WooCommerce…) of the landing page                                                                                     |
| 🔁 **Versions and saved media** (options)               | every version of a grouped ad with its dates, platforms and text; images and videos saved in your run's storage, where Meta's links do not expire                                                                                                                                          |

Every field, with an example, is listed in the **Output** section below.

The four last rows, and the text written in the images, are filled only when their option is ticked (all off by default, each charged only when it returns data). The image and video links Meta gives expire after a few days: tick **Save images and videos** to keep the files.

### ✅ Why use Facebook Ads Library Scraper?

- 🔎 **Every way in, in one run**: keywords, advertisers by name, page link or page ID, single ads by ID, or any Ad Library URL you paste — searched in as many countries as you want.
- 🎛️ **All the Ad Library filters in the form**, plus the ones Meta lacks: how long an ad has run, how many versions it has, creative format, link domains, advertisers and words to exclude, delivery dates.
- 🕵️ **Competitor ads, complete**: the advertiser's EU audience and payer, page owner, audience and spend, all versions of a creative, the real landing page and its product, the contacts of the landing page — each as an option you tick only when you need it.
- 🔔 **Monitoring built in**: tick **Only new ads**, schedule the Actor, and each run returns only what it has never delivered before (an ad it reads again costs one small filter check).
- 🧩 **Nothing twice**: pagination is automatic, an ad found by several searches is saved once, and `searchCountry` tells which country found it.
- 📊 **Market sizing**: **Totals only** returns how many ads the Ad Library has for each keyword, advertiser and country, without reading the ads.
- 🔌 API, scheduling, integrations (Make, Zapier, n8n, Google Sheets…) and JSON/CSV/Excel export via the Apify platform.

### 🚀 How to scrape the Meta Ad Library

1. Create a free Apify account.
2. Open **Facebook Ads Library Scraper**, type a **Search keyword** (e.g. `running shoes`) or fill **Advertisers by name** (e.g. `Nike`), and pick a **Country**.
3. Or paste your own Ad Library URLs into **Ad Library URLs or advertiser pages**: a search (all filters set on the site are kept, pagination is automatic), an advertiser's ads, a single ad or a Facebook page.
4. Set **Max ads** (100 by default, 0 = no limit) — and **Max ads per search** when you run several searches — then click **Start**.
5. Download the dataset in JSON, CSV, Excel or via API.

### 💰 How much does it cost to scrape the Meta Ad Library?

This Actor uses **pay per event** pricing: you pay for each ad saved, plus a small fee per run start. Higher Apify plans pay less per ad; the prices of each plan are shown in the **Pricing** tab. Each option adds its own price, and only when it returns something:

- **Ad details**: per ad delivered with its details.
- **Advertiser info**, **Page transparency**: once per advertiser and per run.
- **Advertiser audience and spend**: once per advertiser and per run, and only when Meta publishes the audience (an empty one is not charged).
- **All versions of grouped ads**: per grouped ad read (an ad alone in its group costs nothing more).
- **Final landing page**: per distinct link followed (ads that share a link, tracking parameters aside, are charged once; an ad without a link costs nothing more).
- **Contacts and shop platform of the landing page**: per website where something is found, once per run (the other ads of that website carry the same contacts at no extra charge; the links of a link shortener count one by one).
- **Save images and videos**: per started 3 MB of each file saved (an image counts once, a 60 MB video 20 times; a file that could not be saved is not charged).
- **Totals only**: per search, for its row of totals.
- **Market statistics**: per search summary delivered (a search with fewer than 10 ads has none and costs nothing).
- **AI image text**: per image in which readable text is found (an image without text costs nothing; up to 10 images per ad).
- **AI speech in videos**: per ad video in which speech is found (music only, no sound or no video costs nothing more).
- **AI labels**: per label judged on an ad written in English (an ad in another language or without text costs nothing more).
- **Ad score**: per ad scored (an ad without a start date has no score and costs nothing more).

The filters Meta does not apply itself, or not exactly (start and delivery dates, days running, versions, formats, domains, excluded advertisers and words), are checked by the Actor on every ad it reads: an ad you keep costs its normal price, an ad a filter drops costs a small filter fee instead. Platform usage (compute, proxy) is included in the price.

### ⚙️ Input

```json
{
    "query": "running shoes",
    "country": "US",
    "maxItems": 200
}
```

Competitor research: two advertisers in two countries, active and stopped ads that ran at least 30 days, with the advertiser's profile:

```json
{
    "advertiserNames": ["Nike", "Adidas"],
    "countries": ["FR", "DE"],
    "activeStatus": "all",
    "minDaysRunning": 30,
    "maxItemsPerQuery": 100,
    "includeAdvertiserInfo": true
}
```

Your own Ad Library URLs (a search and a single ad):

```json
{
    "startUrls": [
        {
            "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shoes&search_type=keyword_unordered"
        },
        { "url": "https://www.facebook.com/ads/library/?id=1563512104518420" }
    ],
    "maxItems": 500
}
```

Monitoring one advertiser, only the ads not delivered before, with their images and videos saved:

```json
{
    "pageIds": ["15087023444"],
    "onlyNew": true,
    "stateKey": "nike-ads",
    "downloadMedia": true
}
```

Market sizing: how many ads two keywords have in three countries, without reading the ads:

```json
{
    "searchQueries": ["protein powder", "creatine"],
    "countries": ["US", "GB", "DE"],
    "onlyTotalCount": true
}
```

| Field                                            | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startUrls`                                      | Links from the Meta Ad Library: a search (`https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shoes&search_type=keyword_unordered`, every filter set on the site is kept, pagination is automatic), an advertiser's ads (`…&view_all_page_id=<page id>`), a single ad (`https://www.facebook.com/ads/library/?id=<ad id>`) or a Facebook page (`https://www.facebook.com/nike`). Max 1 000 URLs. The search fields below are added to them. |
| `query`, `searchQueries`, `exactPhrase`          | Words searched in the ads' text, as typed in the Ad Library search box (`running shoes`); `searchQueries` adds more keywords, one search each; `exactPhrase` matches them as an exact phrase.                                                                                                                                                                                                                                                                                |
| `pageIds`                                        | All the ads of these advertisers: page ID (`15087023444`), page link (`https://www.facebook.com/nike`) or the last part of the link (`nike`). Max 1 000.                                                                                                                                                                                                                                                                                                                     |
| `advertiserNames`                                | Advertiser names as shown in the Ad Library (`Nike`, `Decathlon France`) or Instagram accounts (`@thedemocrats`): the best match is read (exact page name, alias or Instagram account first, then the most liked page), and the page found is returned with each ad (`searchPageId`). Max 100.                                                                                                                                                                               |
| `adIds`                                          | Single ads by their Ad Library ID (`1234567890123456`, the `id=` of an ad link), read in every country and status. Max 1 000.                                                                                                                                                                                                                                                                                                                                                |
| `country`                                        | Country where the ads were shown (`US`, `FR`); `ALL` (the default) covers the whole library.                                                                                                                                                                                                                                                                                                                                                                                 |
| `countries`                                      | More countries: every keyword and advertiser is searched in every country (max 1000 searches per run). Two-letter codes (`FR`, `DE`) or `ALL`; `searchCountry` tells which country found the ad.                                                                                                                                                                                                                                                                             |
| `maxItems`, `maxItemsPerQuery`                   | `maxItems`: most ads saved for the whole run, after deduplication and filters (`0` = no limit). `maxItemsPerQuery`: cap for EACH search (keyword × country, advertiser × country, or pasted URL), `0` = no per-search cap.                                                                                                                                                                                                                                                   |
| `activeStatus`                                   | `active` (default), `inactive` or `all`.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `adType`                                         | `ALL` (default) or one of the Ad Library's categories: `POLITICAL_AND_ISSUE_ADS` (Issues, elections or politics: these come with spend, impressions and audience), `HOUSING_ADS`, `EMPLOYMENT_ADS`, `CREDIT_ADS`, `FINANCIAL_PRODUCTS_AND_SERVICES_ADS`, `UNCATEGORIZED_ADS`.                                                                                                                                                                                                |
| `mediaType`                                      | `all` (default), `image`, `video`, `meme`, `image_and_meme` or `none`.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `publisherPlatforms`                             | Only ads shown on at least one of these platforms: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`. Empty = all.                                                                                                                                                                                                                                                                                                                                         |
| `contentLanguages`                               | Only ads written in these languages, as two-letter codes (`en`, `fr`, `es`). Empty = all.                                                                                                                                                                                                                                                                                                                                                                                    |
| `sortBy`                                         | `impressions` (most impressions first, the site's default) or `newest`. It matters with a cap.                                                                                                                                                                                                                                                                                                                                                                               |
| `isTargetedCountry`                              | Only ads that TARGETED the chosen country, not the ones that merely reached people there.                                                                                                                                                                                                                                                                                                                                                                                    |
| `bylines`                                        | Only political and issue ads whose "Paid for by" line is exactly one of these names (`WALMART INC.`).                                                                                                                                                                                                                                                                                                                                                                        |
| `postedAfter`, `postedBefore`                    | Start date range: a date (`2026-09-01`, the whole day included) or a period before now (`7 days`, `2 weeks`, `1 month`; via the API also `24 hours`). Reads the ad's start date.                                                                                                                                                                                                                                                                                             |
| `deliveredAfter`, `deliveredBefore`              | `deliveredAfter`: still running on or after this date (`2026-09-01` or `30 days`). `deliveredBefore`: stopped on or before it (an ad still running is dropped: needs Ad status set to inactive or all, else the input is refused). Together: the ads that ended inside a period.                                                                                                                                                                                             |
| `minDaysRunning`, `maxDaysRunning`               | Days from the start date to the end date (to today for an active ad): `30` keeps the long-running ads, usually the ones that sell; `0` = no bound.                                                                                                                                                                                                                                                                                                                           |
| `minCollationCount`                              | Only ads whose group has at least this many versions (`3`): advertisers test and scale the creatives that work. `0` = no minimum.                                                                                                                                                                                                                                                                                                                                            |
| `displayFormats`                                 | Only these creative formats: `IMAGE`, `VIDEO`, `CAROUSEL`, `DPA` (catalog), `DCO` (dynamic). Empty = all.                                                                                                                                                                                                                                                                                                                                                                    |
| `includeDomains`, `excludeDomains`               | Keep, or drop, the ads whose link, caption or a card's link goes to one of these domains (`gymshark.com` also matches `fr.gymshark.com`).                                                                                                                                                                                                                                                                                                                                    |
| `excludePageIds`                                 | Drop the ads of these advertisers: page ID, page link or the last part of the link (`nike`) — e.g. your own brand in a keyword search.                                                                                                                                                                                                                                                                                                                                       |
| `excludeKeywords`                                | Drop the ads whose text (body, title, caption, link description or a card's text) contains one of these words (`giveaway`) as a whole word (`cat` keeps "category"), case and accents ignored; a word in Chinese, Japanese, Korean, Thai, Burmese, Khmer or Lao is found anywhere in the text.                                                                                                                                                                               |
| `includeAdDetails`                               | Paid option, off by default: who paid for the ad and who it is for, and for ads shown in the EU, UK or Brazil the audience Meta publishes (EU reach, targeted locations, gender, ages, reach by country, age and gender).                                                                                                                                                                                                                                                    |
| `includeAdvertiserInfo`                          | Paid option, off by default: Facebook likes, Instagram account and followers, verification badges, page category, about text and the amount spent on political ads, once per advertiser.                                                                                                                                                                                                                                                                                     |
| `includePageTransparency`                        | Paid option, off by default: the About tab of the advertiser — confirmed page owner, page creation date, name changes, countries of the page managers, related pages — once per advertiser.                                                                                                                                                                                                                                                                                  |
| `includeAdvertiserAudience`, `audienceTimeframe` | Paid option, off by default: the advertiser's Audience tab over `LAST_7_DAYS`, `LAST_30_DAYS` (default) or `LAST_90_DAYS` — number of ads, amount spent, targeting by gender, age, location, custom and lookalike audiences and language, with the share of spend of each. Published by Meta for advertisers of political and issue ads; others are not charged.                                                                                                             |
| `includeAdVersions`                              | Paid option, off by default: every version of an ad that the Ad Library groups with others, with its dates, platforms and text. Ads alone in their group cost nothing more.                                                                                                                                                                                                                                                                                                  |
| `resolveLandingPages`                            | Paid option, off by default: follows each ad's link through its redirects and tracking links to the final page (URL without tracking, status, title, and for a product page its name, price, brand, availability and rating).                                                                                                                                                                                                                                                |
| `downloadMedia`, `maxMediaPerAd`                 | Paid option, off by default: saves the ad's images and videos (cards included) in the run's storage, as Meta's links expire after a few days; at most 10 files per ad by default (1 to 50), videos over 200 MB skipped.                                                                                                                                                                                                                                                      |
| `extractLandingContacts`                         | Paid option, off by default: e-mails, phone numbers, social links and shop platform (Shopify, WooCommerce, Wix…) found on each ad's landing page, once per domain (once per app for an app store) — a lead list from the advertisers of a search.                                                                                                                                                                                                                            |
| `includeMarketStats`                             | Paid option, off by default: at the end of the run, one summary per search with at least 10 ads delivered, in the MARKET_STATS record of the key-value store (not in the dataset). Cannot be combined with **Totals only**. |
| `imageText`                                      | Paid option, off by default: AI reads the text written in each ad's images (offer, dates, brand, button) into the two image text columns (see Output); Latin-script text only; needs 2 GB of memory. Cannot be combined with **Totals only**. |
| `videoTranscript` | Paid option, off by default: AI writes down what is said in the ad's main video (first 60 seconds of sound) into the video transcript and video language columns (see Output). Music only or no sound = empty and free. Needs 2 GB of memory. Cannot be combined with **Totals only**. |
| `aiLabelNames`                                   | Paid option, off by default: your own labels (up to 20, in English: `discount`, `free shipping`, `testimonial`; write `name: what it means` to say more). AI judges the English text of each ad and adds `aiLabels` (a `score` and a `match` per label). Only ads written in English are labelled. Needs 2 GB of memory. Empty list = off. Cannot be combined with **Totals only**. |
| `includeAdScore` | Paid option, off by default: a 0-100 "winning ad" score for each ad (**adScore**), with the points of each factor (**adScoreFactors**): how long it has been running, how many versions it has, its platforms, its countries and whether it is still active. Computed on the ad's own data, no extra request. Cannot be combined with **Totals only**. |
| `onlyTotalCount`                                 | One row per search with the number of ads the Ad Library has for it, without reading the ads. Cannot be combined with the ad options above.                                                                                                                                                                                                                                                                                                                                  |
| `stateKey`, `onlyNew`, `resetState`              | Monitoring: `onlyNew` skips the ads already delivered under this memory key (`competitor-ads-fr`; letters, digits, dashes and underscores); `resetState` forgets the memory before the run.                                                                                                                                                                                                                                                                                  |
| `runTag`                                         | Any label (`client-a-weekly`), copied into every row to tell your runs apart.                                                                                                                                                                                                                                                                                                                                                                                                |
| Advanced                                         | `proxyConfiguration` (keep **Apify Proxy**, the default: the Actor picks the connection each page needs, included in the price; with your own proxy URLs every request goes through them), `maxConcurrency`, `maxRequestsPerMinute`, `minRequestIntervalMs`, `maxRequestRetries`, `debugLog`.                                                                                                                                                                                |

### 📦 Output

One real ad from a search for `nike` in France (shortened: long texts and media links cut, and most columns that are empty for this ad left out):

```json
{
    "recordType": "ad",
    "id": "1563512104518420",
    "url": "https://www.facebook.com/ads/library/?id=1563512104518420",
    "pageId": "381727498962869",
    "pageName": "Lost Dutchman Leather Goods",
    "pageUrl": "https://facebook.com/lostdutchmanleather",
    "pageCategories": ["Accessories"],
    "pageLikeCount": 139044,
    "isActive": true,
    "status": "ACTIVE",
    "startDate": "2024-07-17T07:00:00.000Z",
    "endDate": "2026-10-21T07:00:00.000Z",
    "daysRunning": 826,
    "publisherPlatforms": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"],
    "collationId": "1157358358844275",
    "collationCount": 1,
    "displayFormat": "VIDEO",
    "title": "🌵Upgrade Your Everyday Carry",
    "bodyText": "Considerately designed & crafted for perfection. Each piece ages uniquely to the owner, meaning no two pieces will patina the same.",
    "caption": "www.lostdutchmanleather.com",
    "linkUrl": "https://www.lostdutchmanleather.com/collections/all",
    "landingDomain": "lostdutchmanleather.com",
    "ctaText": "Shop now",
    "ctaType": "SHOP_NOW",
    "videoUrl": "https://video.fnap7-1.fna.fbcdn.net/o1/v/t2/f2/m412/AQMOPBRiXSyfL5j2VFJ70W98domNTzuti97JYH-EwsL9xuYTV6t6O53_jHU_E70QxIY69gIa4H6tYWqKs4dtmyCa.mp4",
    "spend": null,
    "impressionsIndex": -1,
    "containsDigitalCreatedMedia": false,
    "searchQuery": "nike",
    "searchCountry": "FR",
    "searchUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=FR&q=nike&search_type=keyword_unordered",
    "totalCount": 6318,
    "adDetails": null,
    "versions": null,
    "savedMedia": null,
    "imageText": null,
    "imageTexts": null,
    "videoTranscript": null,
    "videoLanguage": null,
    "videoDuration": null,
    "aiLabels": null,
    "adScore": null,
    "adScoreFactors": null,
    "scrapedAt": "2026-10-21T12:00:00.000Z"
}
```

You can download the dataset in various formats such as JSON, HTML, CSV or Excel.

#### All 99 fields

| Fields                                                                           | What you get                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `recordType`                                                                     | `ad`, or `searchTotal` for the row of a search with **Totals only**                                                                                                                                                                                                                                          |
| `id`, `adArchiveId`, `adId`                                                      | **Ad**: the Ad Library ID (`1563512104518420`), twice, and Meta's internal ad ID when the site gives it                                                                                                                                                                                                      |
| `url`, `adLibraryUrl`                                                            | link to the ad in the Ad Library                                                                                                                                                                                                                                                                             |
| `pageId`, `pageName`, `pageUrl`, `pageProfilePictureUrl`                         | **Advertiser**: page ID, name, link, profile picture                                                                                                                                                                                                                                                         |
| `pageCategories`, `pageLikeCount`, `pageIsDeleted`                               | page categories, likes shown on the ad, deleted page                                                                                                                                                                                                                                                         |
| `byline`, `disclaimerLabel`                                                      | "Paid for by" line of political ads, disclaimer shown on the ad                                                                                                                                                                                                                                              |
| `isActive`, `status`                                                             | running now, `ACTIVE` or `INACTIVE`                                                                                                                                                                                                                                                                          |
| `startDate`, `endDate`, `startDateUnix`, `endDateUnix`                           | **Dates**: ISO 8601 UTC and Unix seconds; for an active ad, the end date is the last day seen running                                                                                                                                                                                                        |
| `daysRunning`, `totalActiveTime`                                                 | days from start to end (to today for an active ad), total active time in seconds as the site gives it                                                                                                                                                                                                        |
| `publisherPlatforms`, `categories`                                               | `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `AUDIENCE_NETWORK`, `THREADS`; Ad Library categories (`POLITICAL`, `HOUSING`…)                                                                                                                                                                                         |
| `collationId`, `collationCount`                                                  | group of identical ads and its number of versions                                                                                                                                                                                                                                                            |
| `displayFormat`                                                                  | `IMAGE`, `VIDEO`, `CAROUSEL`, `DPA` (catalog), `DCO` (dynamic)                                                                                                                                                                                                                                               |
| `title`, `bodyText`, `caption`, `linkDescription`                                | **Creative**: headline, ad text, caption, text under the headline                                                                                                                                                                                                                                            |
| `linkUrl`, `landingDomain`, `utmParameters`                                      | **Link**: URL, domain without `www.`, tracking parameters as an object                                                                                                                                                                                                                                       |
| `ctaText`, `ctaType`                                                             | button text and type (`Shop now`, `SHOP_NOW`)                                                                                                                                                                                                                                                                |
| `imageUrl`, `images`                                                             | first image, every image (original, resized, watermarked)                                                                                                                                                                                                                                                    |
| `videoUrl`, `videoPreviewImageUrl`, `videos`                                     | first video (HD when available), its preview, every video (HD, SD, watermarked)                                                                                                                                                                                                                              |
| `cards`, `cardCount`                                                             | carousel and catalog cards (title, text, link, button, image and video of each)                                                                                                                                                                                                                              |
| `extraTexts`, `extraLinks`, `extraImages`, `extraVideos`                         | other texts, links, images and videos of a dynamic ad                                                                                                                                                                                                                                                        |
| `isReshared`, `brandedContent`                                                   | the ad reshares a post; branded-content partner                                                                                                                                                                                                                                                              |
| `countryIsoCode`, `targetedOrReachedCountries`                                   | country shown on the ad, countries the ad targeted or reached                                                                                                                                                                                                                                                |
| `currency`, `spend`, `spendLower`, `spendUpper`                                  | **Spend** (political and issue ads): the amount as Meta prints it (`$600K - $700K`), its bounds (`600000`, `700000`)                                                                                                                                                                                         |
| `impressionsText`, `impressionsLower`, `impressionsUpper`, `impressionsIndex`    | impressions as shown (`>1M`, `10K-15K`), their bounds, the site's index (`-1` = none)                                                                                                                                                                                                                        |
| `reachEstimate`                                                                  | estimated audience size as Meta prints it (`>1M`)                                                                                                                                                                                                                                                            |
| `containsSensitiveContent`, `containsDigitalCreatedMedia`, `stateMediaRunLabel`  | **Transparency labels**: sensitive content, digitally created or altered media, state-controlled media                                                                                                                                                                                                       |
| `gatedType`, `isAaaEligible`, `hasUserReported`, `reportCount`, `hideDataStatus` | visibility gate, EU ad transparency eligibility, reports, hidden data                                                                                                                                                                                                                                        |
| `regionalRegulationData`, `menuItems`, `fevInfo`                                 | regional rules (financial services, Taiwan anti-scam) and other data the site gives                                                                                                                                                                                                                          |
| `searchQuery`, `searchCountry`, `searchPageId`, `searchUrl`, `totalCount`        | **Search** that found the ad first: keyword, country, advertiser, URL, number of ads the Ad Library has for it. For an advertiser given by name, `searchUrl` holds the name typed and names the search; that advertiser's ads are at `https://www.facebook.com/ads/library/?view_all_page_id=<searchPageId>` |
| `snapshot`                                                                       | the ad's full creative object as Meta returns it (snake_case)                                                                                                                                                                                                                                                |
| `adDetails`, `payer`, `beneficiary`, `euTotalReach`                              | **Ad details** (option): `payer`, `beneficiary`, `targetsEu`, `euTotalReach`, `targetLocations`, `targetGender`, `targetAges`, `reachBreakdown` (by country, age and gender), UK and Brazil transparency; for political ads `ageGender`, `regions`; moderation flags                                         |
| `advertiser`                                                                     | **Advertiser info** (option): `likes`, `igUsername`, `igFollowers`, `igVerified`, `pageVerification`, `pageCategory`, `pageAlias`, `about`, `lifetimeSpend` and `weeklySpend` by "Paid for by" label…                                                                                                        |
| `pageTransparency`                                                               | **Page transparency** (option): `confirmedOwner` (name, address, phone), `createdAt`, `nameChanges`, `adminCountries`, `relatedPages`…                                                                                                                                                                       |
| `advertiserAudience`                                                             | **Advertiser audience** (option): `totalAds`, `totalSpend`, `gender`, `age`, `locations`, `customAudiences`, `lookalikeAudiences`, `languages` with their share of spend; `filled: false` when Meta publishes nothing (not charged)                                                                          |
| `versions`                                                                       | **All versions** (option): ID, link, dates, platforms, format, texts and media of each version; `[]` for an ad alone in its group                                                                                                                                                                            |
| `landingPage`                                                                    | **Final landing page** (option): `finalUrl`, `finalDomain`, `statusCode`, `redirects`, `title`, `metaDescription`, `product` (name, price, currency, brand, availability, rating)                                                                                                                            |
| `savedMedia`                                                                     | **Saved media** (option): for each file `type`, `sourceUrl` (Meta's expiring link), `url` (link in the run's storage), `contentType`, `bytes`; `[]` = the ad has no media                                                                                                                                    |
| `landingContacts`                                                                | **Landing page contacts** (option): `emails`, `phones`, `socialLinks`, `shopPlatform`, `pageUrl`                                                                                                                                                                                                             |
| `imageText`, `imageTexts`                                                        | **AI image text** (option): the text found in the main image, and in every image (main image, other images, carousel cards, video preview; up to 10 per ad), in the same order; `null` for an image without readable text |
| `videoTranscript`, `videoLanguage` | **AI speech in videos** (option): what is said in the first minute of the ad's main video, and its language code (`en`, `fr`…); `null` for an ad without video, a video with music only or no sound, or when the option is off |
| `videoDuration` | **AI speech in videos** (option): length in seconds of the ad's main video; also filled when the video has no speech (nothing charged then); `null` for an ad without video, an unreadable video file, or when the option is off |
| `aiLabels`                                                                       | **AI labels** (option): one entry per label asked, in the order of the input: `label`, `score` (0 to 1) and `match` (true or false); `null` for an ad not in English, without text, or when the option is off |
| `adScore`, `adScoreFactors` | **Ad score** (option): the 0-100 "winning ad" score, and the points of each factor: `longevity` (0-40), `versions` (0-25), `platforms` (0-15), `countries` (0-10), `active` (0-10); `null` for an ad without a start date, or when the option is off |
| `runTag`, `scrapedAt`                                                            | the **Run tag** of the input, when the ad was read                                                                                                                                                                                                                                                           |

Every column is always there, except in the row of **Totals only** (8 columns): a value the site does not give, or an option not ticked, is `null`.

### 💡 Tips

#### How to get more results

Set **Max ads** to `0`, choose `ALL` in **Ad status** and add countries: each keyword or advertiser is searched in each country. Political and issue ads are listed in every country; other ads only where the law makes Meta list them (EU, UK, Brazil…) or where they are running now — so stopped commercial ads are best searched in an EU country.

#### How to reduce costs

The price is per ad, so the levers are **Max ads**, **Max ads per search**, the filters the Ad Library applies itself (status, category, media type, platforms, languages, "Paid for by": nothing is charged for what they leave out) and **Only new ads** for recurring runs (you never pay the full price twice for the same ad; one a run reads again costs a filter check). Tick an option only when you need its data. To know how big a search is before reading it, run it with **Totals only**.

#### Spy on a competitor's ads

Put the brand in **Advertisers by name** (`Nike`) or **Advertisers** (page link or ID), set **Ad status** to `all` and **Min days running** to `30`: the ads still running after a month are usually the ones that work. **Min versions** keeps the creatives the advertiser has scaled; **All versions of grouped ads** returns every variant. **Final landing page** and **Contacts and shop platform of the landing page** show where the traffic goes.

#### Several searches in one run

Fill `searchQueries`, `pageIds`, `advertiserNames` and / or `countries`: the Actor runs one search per keyword × country and per advertiser × country (3 keywords × 4 countries = 12 searches, up to 1000 per run). A single **Search keyword** and **Country** are added to the lists. An ad found by several searches is saved — and charged — once, with the first search that found it. Set **Max ads per search** to give every search its own cap: without it the first searches can use up the whole **Max ads** budget. Pasted URLs are searches of their own, with the same cap.

#### Monitoring: only the new ads

Tick **Only new ads** (`onlyNew`) and schedule the Actor. The first run returns everything; each later run skips the ads already delivered: they are not saved again; each one a run reads again costs one filter check (Meta's "newest" order is not by date, so a run reads them to find the new ones). The memory lives in a named key-value store of your account (`facebook-ads-library-scraper-seen`, up to 150,000 ads per key) and is only updated with ads that really reached the dataset, so a failed run never hides anything. Give each schedule its own `stateKey` (two schedules sharing a key would hide each other's ads), and tick `resetState` once to start over. The Ad Library does not list ads strictly by date, so each search is read up to its cap or its end.

The filters `postedBefore`, `deliveredBefore`, `minDaysRunning` and `minCollationCount` can let an ad through later (it gets older, stops running, or gains versions): with **Only new ads**, an ad they drop is checked again at the next runs, and each check costs the filter fee.

#### Filter by date and by how long ads ran

`postedAfter` and `postedBefore` read the ad's start date; `deliveredAfter` and `deliveredBefore` its end date (today for an active ad). Each takes a date (`2026-09-01`, the whole day is included, UTC) or a period before now (`7 days`, `2 weeks`, `1 month`; via the API also `24 hours` or a full ISO date-time). `postedAfter` and `postedBefore` are also sent to the Ad Library, which then returns mostly the ads of that period. `minDaysRunning` and `maxDaysRunning` count the days from start to end. Filtered-out ads are not saved and do not count in **Max ads** (each ad dropped costs the filter fee, see Pricing); the run summary tells how many were filtered.

#### Keep the images and videos

The image and video links Meta gives (`imageUrl`, `videoUrl`, `images`, `videos`, `pageProfilePictureUrl`) expire after a few days. Tick **Save images and videos** (`downloadMedia`): each file is saved in the run's key-value store and its link written in `savedMedia`, up to **Max media files per ad** (10 by default). A file is charged per started 3 MB (an image counts once, a 60 MB video 20 times), so the price follows the weight you keep in your storage.

#### Size a market with Totals only

Tick **Totals only** (`onlyTotalCount`) with many keywords, advertisers and countries: one row per search with `totalCount`, the number of ads the Ad Library has for it, and no ad is read. A quick way to compare brands or countries before a full run.

#### Market statistics per search

Tick **Market statistics per search** (`includeMarketStats`): at the end of the run, each search with at least 10 ads delivered gets ONE summary in the run's key-value store, in the record `MARKET_STATS` (Output tab; not in the dataset). Each summary holds the number of ads and how many are still active, the number of advertisers and the 10 biggest with their share, the ads by platform and by format, the days the ads ran (smallest, median, 75th percentile, largest), the grouped ads, the top landing domains, buttons and countries, the ads by start month, the spend and impressions Meta publishes (by currency) and the total the Ad Library shows for the search. It is worked out from the ads of that run, so use **Max ads** and the filters to choose what it covers.

#### AI image text

Tick **AI image text** (`imageText`): the text written in the ad images (an offer, dates, a brand name, a button) is read by an AI that runs inside the Actor, and written in `imageText` (the main image) and `imageTexts` (every image of the ad: the main image, the other images, the carousel cards, then the video preview; 10 at most). An image in which no readable text is found gives `null` and is not charged. Only Latin-script text is read (English, French, German, Spanish, Italian, Portuguese…). The option needs **2 GB of memory** (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it. A very large image is skipped.

#### AI speech in videos

Tick **AI speech in videos** (`videoTranscript`): what is said in the ad's main video (the one in `videoUrl`) is written down by an AI that runs inside the Actor, into `videoTranscript`, with the language it hears in `videoLanguage`; the length of that video in seconds is written in `videoDuration` (also when it has no speech). The first 60 seconds of sound are read: that is where an ad says its hook, its offer and its call to action. A video with music only, no sound, or too few words gives `null` and is not charged; an ad without video costs nothing more. The option needs **2 GB of memory** (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it. A very large video file is skipped.

#### AI labels

Fill **AI labels** (`aiLabelNames`) with your own labels, in English (`discount`, `free shipping`, `testimonial`…; up to 20), and an AI that runs inside the Actor judges the text of each ad against each of them. `aiLabels` holds one entry per label: `label`, `score` (from 0 to 1) and `match` (true when the label applies). Write `name: what it means` (for example `competitor: mentions a competing product`) to say more than the name alone. The text judged is the ad's body, title, caption, link description and cards, plus the text read in its images when **AI image text** is ticked too. Only ads written in English receive labels: an ad in another language, or without text, gets `aiLabels: null` and is not charged. The option needs **2 GB of memory** (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it.

#### Ad score

Tick **Ad score** (`includeAdScore`) to sort the ads that look like winners first. Each ad gets `adScore`, from 0 to 100, and `adScoreFactors`, the points of each factor:

| Factor | Points |
|---|---|
| `longevity`: days running | 90 days or more 40 · 60+ 34 · 30+ 28 · 14+ 20 · 7+ 12 · 3+ 6 · less 0 |
| `versions`: identical ads grouped with it | 20 or more 25 · 10+ 20 · 5+ 15 · 2+ 8 · alone 0 |
| `platforms`: Facebook, Instagram, Messenger, Audience Network, Threads | 5 per platform beyond the first, up to 15 |
| `countries`: countries reached or targeted | 5 or more 10 · 2+ 5 · one 0 |
| `active`: still running | 10 |

Advertisers keep paying for the ads that sell: an ad that has run for months, in many versions and on several platforms is a strong sign. The score is computed on the ad's own data, with no extra request, so it is fast. An ad without a start date has no score (`null`) and is not charged.

### 🔌 Integrations and API

Call the Actor via the Apify API, the JavaScript or Python clients, or connect it with integrations and webhooks (Make, Zapier, n8n, Google Sheets, Slack, Airtable…). The dataset can be fetched as JSON or CSV from any tool.

### 🤖 Use with AI agents (MCP)

AI agents (Claude, ChatGPT, Cursor…) can find and run this Actor through the [Apify MCP server](https://mcp.apify.com), billed to their Apify account like any run. It returns one item per ad of the Meta Ad Library (Facebook, Instagram, Messenger, Threads). Actor id: `nice_dev/facebook-ads-library-scraper`; MCP server with this Actor only: `https://mcp.apify.com/?tools=fetch-actor-details,nice_dev/facebook-ads-library-scraper`.

Smallest input, for a cheap first call:

```json
{
    "query": "running shoes",
    "country": "US",
    "maxItems": 10
}
```

Key output fields: `url`, `pageName`, `bodyText`, `title`, `linkUrl`, `startDate`, `daysRunning`, `publisherPlatforms`, `imageUrl` and `videoUrl`.

Cost: pay per ad saved plus a small fee per run start, options only when ticked; see the pricing section above. Cap each call with `maxItems` and, through the API, with the run option `maxTotalChargeUsd`.

### ❓ FAQ

#### Is it legal to scrape the Meta Ad Library?

The Meta Ad Library is published by Meta for ad transparency, and the Actor only reads what it shows publicly to any visitor, without a Facebook account. It logs in to nothing. Results can contain personal data (an advertiser who is a person, a "Paid for by" name, a page owner's address or phone with **Page transparency**, e-mails and phone numbers with the landing page contacts option), which is protected by GDPR and similar laws: do not store it without a legitimate reason. You are responsible for using the data in compliance with Meta's Terms of Use and applicable law. This Actor is not affiliated with Meta Platforms or Facebook.

#### Does it need a login or a proxy?

No Facebook account, no login, no cookies. Keep **Apify Proxy** (the default): the Actor picks the connection each page needs, and it is included in the price. With your own proxy URLs (`proxyUrls`), every request goes through them: Meta shows more than the first 30 ads of a search only to home connections. On the free Apify plan, without your own proxy URLs, you get the first 30 ads of each search (the run ends successfully and says so in its status); the residential connection beyond them is reserved for paid plans. A request Meta turns away ("Rate limit exceeded") is retried at once on a new proxy session, up to 10 times on top of the retries (without a proxy, after a pause of 5 seconds, doubled at each retry up to 150 seconds), and the search goes on from where it stopped.

#### Is the data safe to open in Excel or to show on a web page?

Ad texts, titles and captions are the advertisers' own words, copied as they are (catalog ads keep Meta's placeholders such as `{{product.name}}`). A text can begin with `-`, `+`, `=` or `@` (a phone number, a title such as `-30% today`): Excel and Google Sheets may read such a cell of a CSV file as a formula or as a number. The Actor leaves the text as it is, so that the JSON and the API give the real value: when you open a CSV, import these columns as text. On a web page, escape every field like any text written by a stranger.

#### Known limitations

- Spend, impressions and estimated audience are published by Meta for political and issue ads only, as ranges (`$600K - $700K`): `spend` keeps Meta's text, `spendLower` / `spendUpper` its bounds. For other ads they are `null`.
- Commercial ads are listed by Meta only where the law requires it (EU, UK, Brazil…) or while they run: a stopped commercial ad shown only in the US is not in the Ad Library.
- Meta's image and video links expire after a few days: use **Save images and videos** to keep the files.
- `totalCount` is Meta's own count for the search, before the Actor's filters.
- One search reads at most 10,020 ads (the first 30, then 999 pages of 10). When Meta has more, the run says so in its log, with the total Meta announced: narrow the search (country, dates, advertiser) or run several searches to read the rest.
- **Advertisers by name** reads the best match of the Ad Library's advertiser search: check `pageName` and `pageId`, or use **Advertisers** with the page link or ID when names are close.
- `onlyNew` remembers ad IDs, not their content: an ad whose text or end date changed is not returned again.
- Two runs sharing the same `stateKey` at the same time may both return the same new ad.

**A run that reaches its timeout** stops itself about 45 seconds before it: no new page is asked, what it read is saved and, with `onlyNew`, remembered, and the run ends *Succeeded* with "Stopped before the run's timeout". Resurrect it to go on from there, or give the next run a longer timeout (Run options).

**A run the platform stops without warning** (out of memory)

- Resurrect it: it goes on from where it stood at most a minute before the stop. What it had read since is read again, and the ads already saved are skipped: none is delivered or charged twice, and `maxItems` still counts them.
- With `onlyNew`, the memory is saved after each write (at most once every 2 seconds): resurrect the stopped run and the ads it had saved meanwhile join the memory; leave it stopped for good, and the next run may return the ads of its last 2 seconds once more.

#### Something doesn't work?

The last line of the log counts the ads saved and filtered out, and the requests that failed after every retry. Those requests are listed, with the reason, in the `FAILED_REQUESTS` record of the run's key-value store. A run that saved nothing and had failed requests fails, and its last message gives the cause.

If Meta changes the Ad Library, you are told instead of paying for blank rows. If the first 20 ads read all lack their advertiser, start date, status or platforms, the run saves nothing more, stops and fails, and its last message names the missing field: at most those first ads are charged. An ad that `postedAfter` / `postedBefore` drops because it has no date at all counts among those 20. A run of fewer ads (a scheduled `onlyNew` run that finds a few new ones, a small **Max ads**) is checked at its end, from 5 ads: its ads are already saved, and the run fails with the missing field instead of ending green.

### 🛟 Support

Open an issue in the **Issues** tab with a link to your run: the run log and the `FAILED_REQUESTS` record of the key-value store show exactly which requests failed and why.

# Actor input Schema

## `startUrls` (type: `array`):

Links pasted from the Meta Ad Library (`https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shoes&search_type=keyword_unordered`): every filter set on the site is kept (country, status, ad type, media, platforms, languages, dates, sort) and pagination is automatic. Also accepted: an advertiser's ads (`…&view_all_page_id=<page id>`), a single ad (`https://www.facebook.com/ads/library/?id=<ad id>`) and a Facebook page link (`https://www.facebook.com/nike`), read as that advertiser's ads. When this list is not empty, the search fields below are added to it; filters, caps and monitoring apply to all. Max 1 000 URLs.

## `query` (type: `string`):

Words searched in the ads' text, as typed in the Ad Library search box (e.g. `running shoes`). Empty = no keyword search (use advertisers, ad IDs or URLs instead).

## `searchQueries` (type: `array`):

Several keywords in one run: one search per keyword (times each country below). Added to **Search keyword**; an ad found by several searches is saved once.

## `exactPhrase` (type: `boolean`):

Match the keywords as an exact phrase (the site's "exact phrase" search), instead of ads that contain all the words in any order.

## `pageIds` (type: `array`):

All the ads of these advertisers: Facebook page ID (`15087023444`), page link (`https://www.facebook.com/nike`) or the last part of the link (`nike`). Country, status and the other filters below apply. Max 1 000.

## `advertiserNames` (type: `array`):

Advertiser names as shown in the Ad Library (`Nike`, `Decathlon France`) or Instagram accounts (`@thedemocrats`): each one is looked up in the site's advertiser search and the best match is read (exact page name, alias or Instagram account first, then the most liked page). The page found is returned in `pageId` / `pageName` and `searchPageId`; the rows' `searchUrl` keeps the name as typed (the key of that search, not a link to the advertiser's ads). Max 100.

## `adIds` (type: `array`):

Single ads by their Ad Library ID (`1234567890123456`, the `id=` of an ad link). Read in every country and status. Max 1 000.

## `country` (type: `string`):

Country where the ads were shown. `All countries` covers the whole library. Political and issue ads are listed in every country; other ads only where the law makes Meta list them (EU, UK, Brazil…) or where they are running now.

## `countries` (type: `array`):

Several countries in one run: every keyword and advertiser is searched in every country (3 keywords × 4 countries = 12 searches, max 1000), and `searchCountry` tells which one found the ad. Added to **Country**. Two-letter codes (`FR`, `DE`, `US`) or `ALL`.

## `maxItems` (type: `integer`):

Maximum number of ads to save for the whole run (after deduplication and filters). 0 = no limit.

## `maxItemsPerQuery` (type: `integer`):

Cap for EACH search (keyword × country, advertiser × country, or pasted URL), so that the first search cannot use up the whole **Max ads** budget. 0 = no per-search cap.

## `activeStatus` (type: `string`):

Ads running now, ads that stopped, or both.

## `adType` (type: `string`):

The site's ad category. `Issues, elections or politics` ads come with their spend, impressions and audience.

## `mediaType` (type: `string`):

Only ads with this kind of media.

## `publisherPlatforms` (type: `array`):

Only ads shown on at least one of these platforms. Empty = all platforms.

## `contentLanguages` (type: `array`):

Only ads written in one of these languages, as two-letter codes (`en`, `fr`, `es`). Empty = all languages.

## `sortBy` (type: `string`):

Order in which the site returns the ads (it matters with **Max ads**): most impressions first (the site's default) or most recent first.

## `isTargetedCountry` (type: `boolean`):

Only ads that TARGETED the chosen country (the site's filter), not the ads that merely reached people there.

## `bylines` (type: `array`):

Only political and issue ads whose "Paid for by" line is exactly one of these names, as the Ad Library shows it (`WALMART INC.`). Sent to the site.

## `postedAfter` (type: `string`):

Only ads that started running on or after this date: `2026-09-01`, or a period before now such as `7 days`, `2 weeks`, `1 month` (API: `24 hours` and full ISO date-times work too). Reads the ad's start date (`startDate`).

## `postedBefore` (type: `string`):

Only ads that started running on or before this date (the whole day is included), or longer ago than a period such as `30 days`.

## `minDaysRunning` (type: `integer`):

Only ads that have been running for at least this many days (from start date to end date, or to today for an active ad): long-running ads are usually the ones that sell. 0 = no minimum.

## `maxDaysRunning` (type: `integer`):

Only ads that have been running for at most this many days (fresh tests, not yet scaled). 0 = no maximum.

## `deliveredAfter` (type: `string`):

Only ads still running on or after this date (their end date, or today for an active ad): `2026-09-01` or a period such as `30 days`. Combine with **Started before** to get the ads that ran during a period.

## `deliveredBefore` (type: `string`):

Only ads that STOPPED running on or before this date (their end date; an ad still running is dropped): `2026-09-30` or a period such as `30 days`. Needs **Ad status** set to inactive or all (active ads have not stopped). With **Still running after**, the ads that ended inside a period.

## `minCollationCount` (type: `integer`):

Only ads whose group has at least this many versions (`collationCount`): advertisers test and scale the creatives that work. 0 = no minimum. An ad asked by its ID has no known group size: it is kept.

## `displayFormats` (type: `array`):

Only ads with one of these creative formats (`displayFormat`). Empty = all.

## `includeDomains` (type: `array`):

Keep only the ads whose link, caption or a card's link goes to one of these domains (`gymshark.com` also keeps `fr.gymshark.com`). Tip: also put the domain in **Search keyword** or **More search keywords**: the site then returns mostly those ads.

## `excludePageIds` (type: `array`):

Drop the ads of these advertisers: page ID, page link or the last part of the link (e.g. your own brand in a keyword search).

## `excludeDomains` (type: `array`):

Drop the ads whose link or caption goes to one of these domains (`amazon.com` also drops `www.amazon.com` and `smile.amazon.com`).

## `excludeKeywords` (type: `array`):

Drop the ads whose text (body, title, caption, link description or a card's text) contains one of these words, as a whole word (`cat` keeps "category"; case and accents ignored; a word in Chinese, Japanese, Korean, Thai, Burmese, Khmer or Lao is found anywhere in the text).

## `includeAdDetails` (type: `boolean`):

Open each ad's "See ad details" panel (1 extra request per ad) and add `adDetails`: who paid for the ad and who it is for (`payer`, `beneficiary`), and for ads shown in the EU, UK or Brazil the audience Meta publishes (`euTotalReach`, targeted locations, gender, age range, reach by country, age and gender).

## `includeAdvertiserInfo` (type: `boolean`):

Read each advertiser once per run (1 extra request per advertiser) and add `advertiser` to its ads: Facebook likes, Instagram account and followers, verification badges, page category, alias, about text, and the amount spent on issue / political ads by disclaimer. Charged once per advertiser.

## `includePageTransparency` (type: `boolean`):

Read each advertiser's About tab of the Ad Library once per run (1 extra request per advertiser) and add `pageTransparency`: the confirmed page owner (name, address, phone when published), the page creation date and name changes, the countries of the people who manage the page and how many in each, state media label, related pages and the about text. Charged once per advertiser.

## `includeAdvertiserAudience` (type: `boolean`):

Read each advertiser's Audience tab once per run (1 extra request per advertiser) and add `advertiserAudience`: number of ads and amount spent over the period, and the targeting of its ads by gender, age, location (with exclusions), custom and lookalike audiences and language, with the share of spend of each. Meta publishes it for advertisers running issue, electoral or political ads; others come back empty and are not charged.

## `audienceTimeframe` (type: `string`):

With **Advertiser audience and spend**: the period Meta sums up.

## `includeAdVersions` (type: `boolean`):

The Ad Library groups ads with the same creative (`collationCount` > 1) and shows one. Read the group (at least 1 extra request per grouped ad, one more for each further page of versions) and add `versions`: the ID, dates, platforms and text of each version. Ads alone in their group cost nothing more. An ad asked by its ID comes without its group: `versions` stays null.

## `resolveLandingPages` (type: `boolean`):

Follow each ad's link through its redirects and tracking links (1 extra request per distinct link) and add `landingPage`: the final URL without tracking parameters, its domain, the HTTP status, the page title and, for a product page, the product's name, price, currency, brand, availability and rating. Charged once per distinct link (ads that share a link, tracking parameters aside, are charged once); ads without a link cost nothing more.

## `downloadMedia` (type: `boolean`):

Meta's media links expire after a few days. Save each ad's images and videos (cards included) in the run's key-value store and add their permanent links in `savedMedia`. Charged per 3 MB saved: each file counts one unit per started 3 MB (an image is 1 unit, a 60 MB video 20); a file that could not be saved is not charged.

## `maxMediaPerAd` (type: `integer`):

With **Save images and videos**: the most files saved for ONE ad (a carousel can have 10 cards). Videos larger than 200 MB are skipped.

## `imageText` (type: `boolean`):

AI reads the text written in each ad's images (offer, dates, brand, call to action) and adds `imageText` (main image) and `imageTexts` (every image, up to 10 per ad: the main image, the other images, the carousel cards, then the video preview). Latin-script text only (English, French, German, Spanish, Italian, Portuguese...). Charged per image where text is found; an image without readable text is free. Needs 2 GB of memory (Run options): with less the option is skipped and not charged.

## `videoTranscript` (type: `boolean`):

AI writes down what is said in the ad's main video (first 60 seconds of sound) into `videoTranscript`, with the language in `videoLanguage` and the video length in seconds in `videoDuration`. Charged per video where speech is found; music only or no sound = empty and free. Needs 2 GB of memory (Run options): with less the option is skipped and not charged. Cannot be combined with Totals only.

## `aiLabelNames` (type: `array`):

Your own labels (up to 20, in English, e.g. `discount`, `free shipping`, `testimonial`). AI judges the English text of each ad (body, title, caption, link description, cards, and the text read in the images when AI image text is ticked) and adds `aiLabels`: for each label a `score` (0 to 1) and `match` (true or false). Write `name: what it means` to say more than the name (e.g. `competitor: mentions a competing product`). Only ads written in English are labelled; an ad in another language, or without text, is skipped and not charged. Charged per label evaluated on an ad. Needs 2 GB of memory (Run options): with less the option is skipped and not charged. Empty list = off.

## `includeAdScore` (type: `boolean`):

Adds a 0-100 "winning ad" score to each ad, computed from how long it has been running, how many versions it has, its platforms, countries and whether it is still active, with the points of each factor (`adScore` and `adScoreFactors`). Calculated on the ad's own data, no extra request. Charged per ad scored; an ad without a start date has no score and costs nothing.

## `extractLandingContacts` (type: `boolean`):

Read each ad's landing page once per run (1 extra request per distinct domain, per app for an app store) and add `landingContacts`: e-mail addresses, phone numbers and social links found on it, and the shop platform it runs on (Shopify, WooCommerce, Wix…). Turns the advertisers of a search into a lead list. Charged once per website where something was found (the other ads of that website carry the same contacts at no extra charge).

## `includeMarketStats` (type: `boolean`):

At the end of the run, add ONE summary per search (keyword, advertiser, country or URL) with at least 10 ads delivered by this run, in the key-value store record `MARKET_STATS` (not in the dataset): number of ads and share still active, number of advertisers and the 10 biggest, ads by platform and by format, days running (min, median, 75th percentile, max), grouped ads, top landing domains, top buttons, ads by start month, top countries, the amount spent and impressions Meta publishes (by currency) and the total the Ad Library shows for the search. Calculated on the ads of this run, no extra request. Charged once per summary delivered; a search with fewer than 10 ads has none and costs nothing.

## `onlyTotalCount` (type: `boolean`):

Return ONE row per search with the number of ads the Ad Library has for it (`totalCount`), without reading the ads: a quick way to size a market, an advertiser or a keyword in many countries. 1 request per search.

## `onlyNew` (type: `boolean`):

Skip the ads that a previous run (same **Memory key**) already delivered: they are not saved again; each one read again costs one filter check. First run = everything is new.

## `stateKey` (type: `string`):

Name of the memory used by **Only new ads**. Give each schedule / task its own key (e.g. `competitor-ads-fr`) so that they do not share their memory. Letters, digits, `-` and `_`.

## `resetState` (type: `boolean`):

Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every ad again. Untick it afterwards.

## `runTag` (type: `string`):

Any label (e.g. `client-a-weekly`): copied as it is into every row as `runTag`, to tell your runs apart in a shared dataset or an integration.

## `proxyConfiguration` (type: `object`):

Keep **Apify Proxy** (default): the Actor picks the connection each page needs, included in the price. With your own proxy URLs (`proxyUrls`), every request goes through them: Meta shows more than the first 30 ads of a search only to home connections. On the free Apify plan, without your own proxy URLs, you get the first 30 ads of each search: the residential connection beyond them is reserved for paid plans.

## `maxConcurrency` (type: `integer`):

Maximum number of searches read in parallel (each on its own IP address).

## `maxRequestsPerMinute` (type: `integer`):

Most requests to the site in any 60 seconds, all searches and extra data together. A budget, not an even pace (spread them with the minimum delay below).

## `minRequestIntervalMs` (type: `integer`):

Smallest gap between two requests, in milliseconds. 0 = no gap.

## `maxRequestRetries` (type: `integer`):

Retries per request before it is marked as failed. A request the site turns away ("Rate limit exceeded") is also retried on a new IP address up to 10 times without using up these retries, and the search goes on from where it stopped.

## `debugLog` (type: `boolean`):

Include debug messages in the run log.

## Actor input object example

```json
{
  "startUrls": [],
  "query": "running shoes",
  "searchQueries": [],
  "exactPhrase": false,
  "pageIds": [],
  "advertiserNames": [],
  "adIds": [],
  "country": "US",
  "countries": [],
  "maxItems": 100,
  "maxItemsPerQuery": 0,
  "activeStatus": "active",
  "adType": "ALL",
  "mediaType": "all",
  "publisherPlatforms": [],
  "contentLanguages": [],
  "sortBy": "impressions",
  "isTargetedCountry": false,
  "bylines": [],
  "minDaysRunning": 0,
  "maxDaysRunning": 0,
  "minCollationCount": 0,
  "displayFormats": [],
  "includeDomains": [],
  "excludePageIds": [],
  "excludeDomains": [],
  "excludeKeywords": [],
  "includeAdDetails": false,
  "includeAdvertiserInfo": false,
  "includePageTransparency": false,
  "includeAdvertiserAudience": false,
  "audienceTimeframe": "LAST_30_DAYS",
  "includeAdVersions": false,
  "resolveLandingPages": false,
  "downloadMedia": false,
  "maxMediaPerAd": 10,
  "imageText": false,
  "videoTranscript": false,
  "aiLabelNames": [],
  "includeAdScore": false,
  "extractLandingContacts": false,
  "includeMarketStats": false,
  "onlyTotalCount": false,
  "onlyNew": false,
  "stateKey": "default",
  "resetState": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 8,
  "maxRequestsPerMinute": 240,
  "minRequestIntervalMs": 0,
  "maxRequestRetries": 5,
  "debugLog": 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "running shoes",
    "country": "US",
    "maxItems": 100,
    "videoTranscript": false,
    "includeAdScore": false,
    "includeMarketStats": false,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("nice_dev/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "running shoes",
    "country": "US",
    "maxItems": 100,
    "videoTranscript": False,
    "includeAdScore": False,
    "includeMarketStats": False,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("nice_dev/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": "running shoes",
  "country": "US",
  "maxItems": 100,
  "videoTranscript": false,
  "includeAdScore": false,
  "includeMarketStats": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call nice_dev/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nice_dev/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 <APIFY_API_TOKEN>` 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/AHLY4jHtJqb0dN9le/builds/7vPoAosSeNTiKVSIj/openapi.json
