# Facebook Ads Library Scraper - Meta Ad Library & Spend (`socialscrapers/facebook-ads-library-scraper`) Actor

Facebook Ads Library scraper for Meta's Ad Library: ads by keyword, advertiser Page or URL with text, images, videos, carousels, dates, platforms, spend, impressions and reach. Filter by country, platform, language, media and date. No login, no cookies. $0.35 per 1,000 ads.

- **URL**: https://apify.com/socialscrapers/facebook-ads-library-scraper.md
- **Developed by:** [Social Scrapers](https://apify.com/socialscrapers) (community)
- **Categories:** Marketing, Social media, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.28 / 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

This **Facebook Ads Library Scraper** extracts ads from **Meta's public Ad Library** ([facebook.com/ads/library](https://www.facebook.com/ads/library/)): search by keyword, by advertiser Page, or paste Ad Library URLs from your browser, and get every ad's text, headline, link and call to action, images, videos and carousel cards, start and end dates, active status and platforms, plus spend, impressions and "Paid for by" for political and issue ads. Filter by country, platform, language, media type, ad category and date, or sort by impressions. **No Facebook account, no login, no cookies.** It costs **$0.35 per 1,000 ads**.

### What does Facebook Ads Library Scraper do?

- 🔎 **Three ways to search**: keywords (any words or an exact phrase), advertiser Pages (a Page URL, @handle or numeric Page id), and Ad Library URLs copied from your browser.
- 🎛️ **Every Ad Library filter**: country, ad category (all ads, or political and issue, housing, employment and credit ads), active status, media type (images, videos, memes, no media), platforms (Facebook, Instagram, Audience Network, Messenger, Threads, WhatsApp), ad language, the date range an ad was shown in, and sorting by impressions. Ad Library URLs keep all of their own filters too.
- 🖼️ **The whole creative**: ad text, headline, description, link, caption, call-to-action button, full-size images, HD and SD video links with their preview images, and every card of carousel, catalog and dynamic-creative ads.
- 🗳️ **Political and issue ads**: amount spent, impressions and estimated audience as ranges (with numeric bounds), currency, the "Paid for by" line and the contact details the advertiser submitted.
- 🇪🇺 **Optional ad details**: turn on `includeAdDetails` for the audience of political and issue ads by age, gender and region; the reach, targeting, payer and beneficiary of ads shown in the European Union; and facts about the advertiser's Page (likes, Instagram followers, verification).
- ♾️ **No cap**: collect a set number of ads per search, or every ad it lists (`maxAds: 0`).
- 💸 **Pay only for ads delivered**: searches with no results cost nothing, and the run stops cleanly at the spending limit you set.

Because it runs on the Apify platform, you also get the API, scheduling, integrations, monitoring and proxy rotation without writing any code.

### What data can you extract from the Facebook Ad Library?

One dataset item per ad. Every field is always present: `null`, `false` or an empty list means the Ad Library shows nothing for it.

| Field | Type | Description |
|---|---|---|
| `adArchiveId` | string | The ad's Ad Library id. |
| `adId` | string or null | Facebook's own ad id, when shown (rarely). |
| `url` | string | The ad in the Ad Library. |
| `pageId`, `pageName`, `pageUrl` | string or null | The advertiser's Page. |
| `pageProfilePictureUrl` | string or null | The Page's picture. |
| `pageLikeCount` | integer or null | The Page's likes. |
| `pageCategories` | array | The Page's categories. |
| `pageIsDeleted` | boolean | The Page no longer exists. |
| `isActive` | boolean | The ad is running now. |
| `startDate`, `endDate` | string or null | First and last day shown, ISO 8601 UTC. For an active ad, `endDate` is the latest day it was seen running. |
| `publisherPlatforms` | array | `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp`, ... |
| `displayFormat` | string or null | `IMAGE`, `VIDEO`, `CAROUSEL`, `DCO` (dynamic creative), `DPA` (catalog ad), ... |
| `body` | string or null | The ad text. |
| `title`, `linkDescription`, `caption` | string or null | Headline, description and display link. Catalog ads have these per product, in `cards`. |
| `linkUrl` | string or null | Where the ad leads. |
| `ctaText`, `ctaType` | string or null | The call-to-action button (`Shop now`, `SHOP_NOW`). |
| `images` | array | `originalUrl` and `resizedUrl` of each image. |
| `videos` | array | `hdUrl`, `sdUrl` and `previewImageUrl` of each video. |
| `cards` | array | Carousel, catalog and dynamic-creative cards: `title`, `body`, `caption`, `linkUrl`, `linkDescription`, `ctaText`, `ctaType`, image and video links. |
| `extraTexts`, `extraLinks`, `extraImages` | array | More variants of a dynamic-creative ad. |
| `brandedContent` | object or null | The partner Page of a branded-content ad: `pageId`, `pageName`, `pageUrl`. |
| `collationId`, `collationCount` | string / integer or null | The group of ads sharing this creative, and how many ads it has. |
| `categories` | array | `UNKNOWN`, `POLITICAL`, `HOUSING`, `EMPLOYMENT`, `CREDIT`. |
| `byline`, `disclaimerLabel` | string or null | The "Paid for by" line of political and issue ads. |
| `spend`, `impressions`, `reachEstimate` | object or null | Political and issue ads: `text` as printed (`$10K-$15K`, `>1M`) with `lowerBound` and `upperBound` as numbers. |
| `currency` | string or null | Currency of `spend`. |
| `targetedOrReachedCountries` | array | Countries, when the Ad Library lists them. |
| `containsSensitiveContent`, `containsDigitallyCreatedMedia` | boolean | Ad Library labels. |
| `stateMediaLabel` | string or null | State-controlled media label. |
| `gatedType`, `hideDataStatus`, `isAaaEligible` | string / boolean | Ad Library status flags (`isAaaEligible`: the ad carries EU transparency data). |
| `advertiserContact` | object or null | Political and issue ads: `phone`, `email`, `website`, `address` and `submittedOn` as the advertiser submitted them. |
| `details` | object or null | With `includeAdDetails`: `ageGenderDistribution`, `regionDistribution` (shares as fractions of 1), `euTransparency` (`totalReach`, targeted ages, gender and locations, `reachByCountryAgeGender`), `payerBeneficiaries`, and `advertiser` (handle, category, likes, verification, Instagram username and followers). |
| `input`, `inputType` | string | The search term, Page or URL the ad came from, and which list it was in. |
| `scrapedAt` | string | When the ad was read, ISO 8601 UTC. |

### How to scrape the Facebook Ad Library

1. Click **Try for free** (or **Start**) on this page.
2. Add **search terms** (for example `running shoes`), advertiser **Pages** (`https://www.facebook.com/<page-name>`), or **Ad Library URLs** copied from facebook.com/ads/library.
3. Pick the filters you need: country, active status, platforms, languages, media type, dates, sort order.
4. Set **Max ads** per search (`0` for every ad) and click **Start**. Each search reads about 300 ads a minute.
5. Download the ads from the **Output** tab as JSON, CSV, Excel or HTML, or read them through the API.

### How much does it cost to scrape Facebook ads?

**$0.35 per 1,000 ads**, platform usage and proxies included, with or without `includeAdDetails`. You pay one `ad` event for each ad saved, nothing else:

| Your Apify plan | Price per 1,000 ads |
|---|---|
| Free and Starter (Bronze) | $0.35 |
| Scale (Silver) | $0.315 (−10%) |
| Business (Gold) | $0.28 (−20%) |

Two examples:

- **1,000 ads for one keyword** = **$0.35**.
- **Every active ad of 10 competitors, about 2,000 ads** = **$0.70**.

Searches with no results, and Pages that cannot be found, cost nothing. To cap a run's cost, set **Maximum cost per run** in the run options: the scraper stops cleanly once it is reached and keeps everything scraped so far. Apify's free plan comes with monthly usage credit, enough to try this scraper on thousands of ads.

### Input example

Give at least one of `searchTerms`, `pageUrls` or `adLibraryUrls`.

```json
{
  "searchTerms": ["running shoes", "meal kit"],
  "pageUrls": ["https://www.facebook.com/<page-name>"],
  "adLibraryUrls": [
    "https://www.facebook.com/ads/library/?active_status=all&ad_type=political_and_issue_ads&country=US&media_type=all&q=climate&search_type=keyword_unordered"
  ],
  "country": "US",
  "activeStatus": "active",
  "mediaType": "all",
  "platforms": ["instagram"],
  "languages": ["en"],
  "sortBy": "impressions_high",
  "dateFrom": "30 days",
  "maxAds": 1000,
  "includeAdDetails": false,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

| Field | Type | Description |
|---|---|---|
| `searchTerms` | array of strings | Keywords, one search per term, as typed into the Ad Library search box. |
| `pageUrls` | array of strings | Advertiser Pages: `https://www.facebook.com/<page-name>`, an @handle, or the numeric Page id (the `view_all_page_id` of an Ad Library link). Share links from the Facebook app (`https://www.facebook.com/share/…`, `fb.me/…`) and links to one of the Page's posts work too. |
| `adLibraryUrls` | array of strings | Searches copied from the address bar on facebook.com/ads/library. All their filters are kept; a link to one ad (`?id=...`) returns that ad. |
| `country` | string, default `ALL` | Where the ads were shown: a two-letter code such as `US`, `GB` or `DE`, or `ALL`. |
| `adType` | string, default `all` | `all`, `political_and_issue_ads`, `housing_ads`, `employment_ads` or `credit_ads`. |
| `activeStatus` | string, default `active` | `active`, `inactive` or `all`. |
| `mediaType` | string, default `all` | `all`, `image`, `video`, `meme`, `image_and_meme` or `none`. |
| `exactPhrase` | boolean, default `false` | Match search terms as an exact phrase. |
| `dateFrom`, `dateTo` | string, optional | Only ads shown between these days: a date (`2026-01-31`, `2026-1-31`, `31/01/2026`, `Jan 31 2026`) or an age (`30 days`, `2w`, `3 months`, `yesterday`). With both day and month 12 or less (`01/02/2026`) the date is read month/day/year. An ad that started earlier but still ran in the range is included, as in the Ad Library. |
| `platforms` | array, optional | Only ads shown on these platforms: `facebook`, `instagram`, `audience_network`, `messenger`, `threads`, `whatsapp`. Empty = all. |
| `languages` | array, optional | Only ads in these languages: two-letter codes such as `en`, `es`, `de`. Empty = all. |
| `sortBy` | string, default `default` | `default` (the Ad Library's order), `impressions_high` or `impressions_low`. |
| `maxAds` | integer, default `100` | Ads to collect for each search term, Page and URL. `0` = every ad the search lists. |
| `includeAdDetails` | boolean, default `false` | Add each ad's details (audience breakdowns, EU transparency, advertiser facts). Slower; same price per ad. |
| `proxyConfiguration` | object, default Apify Proxy `RESIDENTIAL` | Proxy settings. Keep the residential default. |

The filters (`country` to `sortBy`) apply to search terms and Pages. An Ad Library URL keeps its own filters and takes from these fields only what it does not set.

### Output example

A real item from a test run, with names, texts, links and ids replaced by placeholders and long media links shortened:

```json
{
  "adArchiveId": "<ad-id>",
  "adId": null,
  "url": "https://www.facebook.com/ads/library/?id=<ad-id>",
  "pageId": "<page-id>",
  "pageName": "<advertiser name>",
  "pageUrl": "https://www.facebook.com/<page-name>/",
  "pageProfilePictureUrl": "https://scontent.xx.fbcdn.net/v/<image-path>.jpg?<signed-parameters>",
  "pageLikeCount": 3400,
  "pageCategories": ["Community Center"],
  "pageIsDeleted": false,
  "isActive": true,
  "startDate": "2026-06-01T07:00:00.000Z",
  "endDate": "2026-11-07T08:00:00.000Z",
  "publisherPlatforms": ["facebook", "instagram"],
  "displayFormat": "IMAGE",
  "body": "<ad text>",
  "title": "<headline>",
  "caption": "<shop-domain>",
  "linkUrl": "https://<shop-domain>/<landing-page>",
  "linkDescription": "<link description>",
  "ctaText": "Learn more",
  "ctaType": "LEARN_MORE",
  "images": [
    {
      "originalUrl": "https://scontent.xx.fbcdn.net/v/<image-path>.jpg?<signed-parameters>",
      "resizedUrl": "https://scontent.xx.fbcdn.net/v/<image-path>.jpg?stp=dst-jpg_s600x600&<signed-parameters>"
    }
  ],
  "videos": [],
  "cards": [],
  "extraTexts": [],
  "extraLinks": [],
  "extraImages": [],
  "brandedContent": null,
  "collationId": "<group-id>",
  "collationCount": 1,
  "categories": ["UNKNOWN"],
  "byline": null,
  "disclaimerLabel": null,
  "spend": null,
  "currency": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedOrReachedCountries": [],
  "containsSensitiveContent": false,
  "containsDigitallyCreatedMedia": false,
  "stateMediaLabel": null,
  "gatedType": "ELIGIBLE",
  "hideDataStatus": "NONE",
  "isAaaEligible": true,
  "advertiserContact": null,
  "details": null,
  "input": "running shoes",
  "inputType": "searchTerm",
  "scrapedAt": "2026-11-08T02:19:21.282Z"
}
```

A political ad carries its spend and reach, and with `includeAdDetails` its audience:

```json
{
  "categories": ["POLITICAL"],
  "byline": "<paid for by>",
  "disclaimerLabel": "PAID_FOR_BY",
  "spend": { "text": "€7K-€8K", "lowerBound": 7000, "upperBound": 8000 },
  "currency": "EUR",
  "impressions": { "text": ">1M", "lowerBound": 1000000, "upperBound": null },
  "reachEstimate": { "text": ">1M", "lowerBound": 1000000, "upperBound": null },
  "advertiserContact": { "phone": "<phone>", "email": "<email>", "website": "<website>", "address": "<city, region>", "submittedOn": "Submitted on 30 Mar 2022" },
  "details": {
    "ageGenderDistribution": [
      { "ageRange": "18-24", "female": 0.13, "male": 0.4, "unknown": 0 },
      { "ageRange": "25-34", "female": 0.04, "male": 0.21, "unknown": 0 }
    ],
    "regionDistribution": [
      { "region": "Uttar Pradesh", "share": 0.11 },
      { "region": "Maharashtra", "share": 0.09 }
    ],
    "euTransparency": null,
    "payerBeneficiaries": [],
    "advertiser": { "pageAlias": "<handle>", "pageCategory": "Organisation", "pageLikes": 1250000, "pageVerification": "BLUE_VERIFIED", "entityType": "PERSON_PROFILE", "about": "<about text>", "profilePhotoUrl": "<image link>", "coverPhotoUrl": "<image link>", "instagramUsername": "<handle>", "instagramFollowers": 830000, "instagramVerified": true }
  }
}
```

### Use cases

- **Competitor ad research:** see every ad a competitor is running right now, in which countries and on which platforms, and how long each one has been live.
- **Creative inspiration:** collect hooks, headlines, calls to action, images and videos that work in your niche, and study long-running ads (the ones advertisers keep paying for).
- **Market and trend monitoring:** run a search on a schedule and track which new ads appear for a keyword or a set of advertisers.
- **Political ad transparency:** follow spend, reach and audience of ads about social issues, elections or politics, by advertiser or topic.
- **Datasets:** gather ad copy and media for analysis, classification or training data.

### Use Facebook Ads Library Scraper via API, Python, JavaScript and integrations

Run the scraper from your own code with the [Apify API](https://docs.apify.com/api/v2) or an Apify client:

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
const run = await client.actor('socialscrapers/facebook-ads-library-scraper').call({
    searchTerms: ['running shoes'],
    country: 'US',
    maxAds: 1000,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

```python
from apify_client import ApifyClient

client = ApifyClient("MY-APIFY-TOKEN")
run = client.actor("socialscrapers/facebook-ads-library-scraper").call(
    run_input={"searchTerms": ["running shoes"], "country": "US", "maxAds": 1000}
)
for ad in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(ad["pageName"], ad["startDate"], ad["body"])
```

- **Schedules**: run a search every day and track which new ads appear for a keyword or a set of advertisers.
- **Integrations**: send the ads to Google Sheets, Slack, Airtable, Make, Zapier or n8n, or trigger your own webhook when a run finishes.
- **AI agents**: call the scraper as a tool through the Apify MCP server.

### Limits

- **What the Ad Library shows logged out.** Spend, impressions and audience data exist only for political and issue ads (and EU transparency data for ads shown in the EU); other ads show their creative, dates and platforms.
- **Some ads hide their creative from logged-out visitors.** About 3% of ads in our tests have `gatedType` `LOGGED_OUT`: they come with their advertiser, text, dates and platforms, but without images, videos or a headline.
- **Each search stands alone.** An ad that matches several of your searches is returned once for each of them; `input` says which.
- **One country per search.** The Ad Library searches one country, or all of them. Run one search per country to compare countries.
- **Ads sharing a creative.** The Ad Library groups ads that share a creative and lists one or a few of them; `collationCount` says how many ads the group has.
- **Media links expire.** Image and video links point to Facebook's CDN, which expires them after some days. Download media promptly if you need it.
- **Residential proxy recommended.** Facebook refuses many data-center IP addresses, so keep the default Apify Proxy `RESIDENTIAL` setting.
- **Share links work for Pages.** A share link from the Facebook app (`https://www.facebook.com/share/…`, `fb.me/…`) or a link to one of a Page's posts is followed to the Page, at no charge.

### FAQ

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

The Ad Library is a public transparency tool that Meta shows to anyone, logged in or not, and this scraper only reads what it shows to logged-out visitors. Political ads can include personal data of the people behind them, which laws such as the GDPR protect, so collect only what you need for a legitimate purpose. Apify explains the basics in [Is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/).

#### Do I need a Facebook account or cookies?

No. The Actor reads only what the Ad Library shows to visitors who are not logged in.

#### How do I scrape exactly the search I see in my browser?

Set up the search on facebook.com/ads/library, copy the address bar, and paste it into `adLibraryUrls`. Every filter in it is kept.

#### Why did I get fewer ads than `maxAds`?

The search has fewer results, or the run reached its maximum total charge. The run log says which, for each search.

#### Why did my run finish with no ads?

No ad matched the search and its filters, the Page was not found, or Facebook refused the requests even after 5 attempts on fresh IPs. The run still ends **Succeeded**, its status message says which, and nothing is charged. A run ends **Failed** only when Facebook refused every one of 3 or more searches (the scraper is then being blocked) or could not read any of the searches at all.

#### What do the dates filter?

`dateFrom` and `dateTo` keep ads that were shown at some point between those days, the Ad Library's own date filter. An ad that started a year ago and still runs is included.

#### How fast is it?

Each search reads about 300 ads a minute, and up to 8 searches run side by side: in our tests, 300 ads from three searches took 25 seconds and 1,000 ads from one search about 3.5 minutes. `includeAdDetails` adds one request per ad.

#### Can I get spend and impressions for all ads?

The Ad Library publishes them only for ads about social issues, elections or politics. For ads shown in the EU, `includeAdDetails` adds the reach and targeting the EU requires.

#### Can I run it on a schedule or from my own code?

Yes. Use Apify schedules, the Apify API and client libraries, webhooks, or integrations such as Make, Zapier or n8n.

### Other scrapers by Social Scrapers

| Scraper | What it gets |
|---|---|
| [Facebook Pages Scraper](https://apify.com/socialscrapers/facebook-profile-scraper) | Public details of Facebook Pages and profiles: contact info, address, rating |
| [Facebook Posts Scraper](https://apify.com/socialscrapers/facebook-profile-posts-scraper) | Posts from Facebook profiles and Pages |
| [Facebook Groups Scraper](https://apify.com/socialscrapers/facebook-groups-scraper) | Posts from public Facebook groups |
| [Instagram Profile Scraper](https://apify.com/socialscrapers/instagram-profile-scraper) | Instagram profiles and their latest posts |
| [Instagram Post Scraper](https://apify.com/socialscrapers/instagram-post-scraper) | Instagram posts, reels and comments |
| [Threads Scraper](https://apify.com/socialscrapers/threads-scraper) | Threads profiles, posts and replies |
| [X (Twitter) Profile Scraper](https://apify.com/socialscrapers/x-profile-scraper) | X profiles: bio, followers, counts |
| [Reddit Scraper](https://apify.com/socialscrapers/reddit-scraper) | Reddit posts, comments, users and search |
| [Quora Scraper](https://apify.com/socialscrapers/quora-scraper) | Quora questions, answers and profiles |
| [YouTube Scraper](https://apify.com/socialscrapers/youtube-scraper) | YouTube videos, channels, search and comments |
| [YouTube Transcript Scraper](https://apify.com/socialscrapers/youtube-transcript-scraper) | Transcripts and captions of YouTube videos |
| [LinkedIn Jobs Scraper](https://apify.com/socialscrapers/linkedin-jobs-scraper) | LinkedIn job listings |

# Actor input Schema

## `searchTerms` (type: `array`):

Keywords to search ads for, one search per term, as you would type them into the Ad Library's search box. The filters below apply.

## `pageUrls` (type: `array`):

Facebook Pages whose ads you want: a Page URL such as <code>https://www.facebook.com/\<page-name></code>, or the Page's numeric id (the <code>view_all_page_id</code> of an Ad Library link). Share links from the Facebook app (<code>https://www.facebook.com/share/…</code>, <code>fb.me/…</code>) and links to one of the Page's posts work too. The filters below apply.

## `adLibraryUrls` (type: `array`):

Searches copied from your browser's address bar on <code>https://www.facebook.com/ads/library/</code>. Every filter in the URL is kept (country, category, status, media, platforms, languages, dates, sorting); a filter the URL does not set comes from the fields below. A link to one ad (<code>?id=...</code>) returns that ad.

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

Where the ads were shown: a two-letter country code such as <code>US</code>, <code>GB</code> or <code>DE</code>, or <code>ALL</code> for every country.

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

All ads, or only one of the categories the Ad Library keeps extra data for. Political and issue ads come with spend, impressions and the "Paid for by" line.

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

Ads running now, ads that have stopped, or both.

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

Only ads with this kind of media.

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

Match each search term as an exact phrase instead of any order of its words.

## `dateFrom` (type: `string`):

Only ads shown on or after this day. Pick a date or an age, or type one: a date (<code>2026-01-31</code>, <code>31/01/2026</code>, <code>Jan 31 2026</code>) or an age such as <code>30 days</code>, <code>7 days</code>, <code>2w</code> or <code>3 months</code>. This is the Ad Library's date filter: an ad that started earlier but still ran on that day is included.

## `dateTo` (type: `string`):

Only ads shown on or before this day: a date (<code>2026-01-31</code>, <code>31/01/2026</code>, <code>Jan 31 2026</code>) or an age such as <code>7 days</code> or <code>yesterday</code>.

## `platforms` (type: `array`):

Only ads shown on these platforms, for example Instagram only. Leave empty for every platform.

## `languages` (type: `array`):

Only ads in these languages: two-letter codes such as en, es or de, one per line. Leave empty for every language.

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

The Ad Library's own order (the default), or ads with the most or the fewest impressions first.

## `maxAds` (type: `integer`):

How many ads to collect for each search term, Page and Ad Library URL, for example 1000. 0 = every ad the search lists.

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

Also open each ad's details: the audience by age, gender and region for political and issue ads; reach, targeting, payer and beneficiary for ads shown in the European Union; the advertiser's Page facts. Slower (one more request per ad); the price per ad is the same.

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

Apify Proxy RESIDENTIAL (the default) is recommended: Facebook refuses many data-center IP addresses. Apify Proxy without the RESIDENTIAL group is switched to RESIDENTIAL (your country is kept), because Facebook turns datacenter IPs away; residential traffic is included in the price.

## Actor input object example

```json
{
  "searchTerms": [
    "running shoes"
  ],
  "country": "ALL",
  "adType": "all",
  "activeStatus": "active",
  "mediaType": "all",
  "exactPhrase": false,
  "sortBy": "default",
  "maxAds": 20,
  "includeAdDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "searchTerms": [
        "running shoes"
    ],
    "maxAds": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("socialscrapers/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 = {
    "searchTerms": ["running shoes"],
    "maxAds": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("socialscrapers/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 '{
  "searchTerms": [
    "running shoes"
  ],
  "maxAds": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call socialscrapers/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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