# Facebook Ads Library Scraper (`aboo.script/facebook-ads-scraper`) Actor

\[💰$2 / 1K] Meta Ad Library scraper for Facebook, Instagram, Messenger and Threads ads. No login, no API key. Search by keyword, advertiser page or ad URL with country, date, platform and media filters. Get ad copy, images, videos, carousel cards, dates, page info, spend and reach.

- **URL**: https://apify.com/aboo.script/facebook-ads-scraper.md
- **Developed by:** [Aboo Script](https://apify.com/aboo.script) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Facebook Ads Library Scraper

![Facebook Ads Library Scraper](https://i.ibb.co/ZpBD4gw0/facebook-ads-banner.png)

**Facebook Ads Library Scraper** extracts ads from the [Meta Ad Library](https://www.facebook.com/ads/library/) into clean, structured data you can download as JSON, CSV, Excel, or HTML. Paste an Ad Library search, advertiser page, or ad URL, or type a few keywords, and get the ad copy, images, videos, start and end dates, platforms, advertiser details, and spend and reach for political ads. No account or login required.

### Introduction

The [Meta Ad Library](https://www.facebook.com/ads/library/) is Meta's public archive of ads running on Facebook, Instagram, Messenger, Threads, and the Audience Network. Marketers, agencies, researchers, and journalists use it to see which ads a brand is running, how long they run, and, for political and issue ads, who paid for them and how much was spent.

This actor collects the same public information you see in your browser and turns it into a ready-to-use dataset. You can run it once, schedule it to run daily, or connect it to your own tools.

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

- 🆔 Ad Library ID, direct ad URL, and number of ad versions
- 🏢 Advertiser name, page URL, profile picture, page likes, and page categories
- 📝 Ad text, headline, caption, link description, and call-to-action button
- 🔗 Landing page link and extra links
- 🖼️ Images, videos (HD and SD), video preview images, and carousel cards
- 📅 Active status, start date, and end date
- 📱 Platforms where the ad runs (Facebook, Instagram, Messenger, Threads, Audience Network) and ad format
- 💰 Spend, impressions, reach estimate, currency, "paid for by" line, and payer for political and issue ads
- 🌍 Targeted or reached countries, ad categories, and AI-generated or sensitive content flags
- 📊 Total number of ads found for your search

### Use Cases

- 📈 **Market research**: see which offers, messages, and formats are being advertised in your niche right now.
- 🕵️ **Competitor monitoring**: track every ad a competitor runs, when it started, and on which platforms.
- 🎨 **Creative inspiration**: collect ad copy, images, and videos to brief designers and copywriters.
- 🗳️ **Political ad research**: follow spend, impressions, and payers of political and issue ads.
- 🤝 **Lead generation**: build lists of active advertisers in any market.
- 🤖 **AI and automation**: feed clean, structured data into spreadsheets, dashboards, or AI workflows.

### How to scrape the Meta Ad Library step by step

1. Paste one or more Ad Library URLs into **Ad Library URLs**, or type keywords into **Search keywords**.
2. Set **Maximum number of ads** to how many ads you want per URL or per keyword.
3. Optionally pick filters for your keywords, such as country, active status, ad category, or platforms.
4. Click **Start** and wait for the run to finish.
5. Download your data in JSON, CSV, Excel, or HTML from the **Output** tab.

### Input

- **Ad Library URLs**: Meta Ad Library URLs to scrape. Supported pages: keyword search results, an advertiser's page of ads (`view_all_page_id`), and a single ad (`?id=`). Any filters you apply on the website (country, active status, ad category, media type, platforms, languages, dates) are kept in the results.
- **Search keywords**: keywords to search in the Ad Library. Each keyword is scraped separately.
- **Maximum number of ads**: how many ads to collect for each URL or keyword. Default is 5. Use 0 for no limit.
- **Country**: two-letter country code where the ads ran (for example US, GB, DE), or ALL for every country. Default is ALL.
- **Active status**: active ads, inactive ads, or both. Default is active ads.
- **Ad category**: all ads, issues, elections or politics, housing, employment, or financial products and services.
- **Media type**: all media, images, videos, memes, images and memes, or ads without image or video.
- **Keyword match**: match any of the words, or the exact phrase.
- **Platforms**: only ads shown on Facebook, Instagram, Messenger, Audience Network, or Threads. Leave empty for all platforms.
- **Started on or after** and **Started on or before**: only ads that started running within these dates.
- **Proxy configuration**: residential proxies are used by default and are required to collect more than the first 30 ads of a search.

The filters from Country to Started on or before apply to search keywords only. You can use Ad Library URLs, search keywords, or both in the same run.

### Input Examples

Scrape an Ad Library search URL:

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all"
    }
  ],
  "maxResults": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

Search by keywords:

```json
{
  "searchQueries": ["running shoes"],
  "maxResults": 5,
  "country": "ALL",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

### Output

Each ad is saved as one item in the dataset. Here is an example of a single item (long media links are shortened):

```json
{
  "url": "https://www.facebook.com/ads/library/?id=3185826644950547",
  "adArchiveId": "3185826644950547",
  "pageId": "159616034235",
  "pageName": "Walmart",
  "pageUrl": "https://www.facebook.com/walmart/",
  "pageProfilePictureUrl": "https://scontent.fmlg11-1.fna.fbcdn.net/v/t39.35426-6/800925447_1071719669102822_853143289454951291_n.jpg?...",
  "pageLikeCount": 31924748,
  "pageCategories": ["Retail company"],
  "isActive": true,
  "startDate": "2026-09-09T07:00:00.000Z",
  "endDate": "2026-10-26T07:00:00.000Z",
  "publisherPlatforms": ["Facebook", "Instagram"],
  "displayFormat": "Dynamic Creative",
  "body": "More brands than the eye can see 👓 ✨ Oscar by Oscar de la Renta, Nike, DKNY & more. Who knew?",
  "title": "Prescription Glasses - Walmart.com",
  "caption": "walmart.com",
  "linkUrl": "https://www.walmart.com/cp/prescription-glasses/1907657",
  "linkDescription": null,
  "ctaText": "Shop now",
  "images": [],
  "videos": [],
  "cards": [
    {
      "title": null,
      "body": "More brands than the eye can see 👓 ✨ Oscar by Oscar de la Renta, Nike, DKNY & more. Who knew?",
      "caption": null,
      "linkUrl": "https://www.walmart.com/cp/prescription-glasses/1907657",
      "linkDescription": null,
      "ctaText": "Shop Now",
      "imageUrl": null,
      "resizedImageUrl": null,
      "videoHdUrl": "https://video.fmlg11-1.fna.fbcdn.net/o1/v/t2/f2/m366/AQMx3InKp7wOTjWc-VESMtrx5Nc3VAFcrZ2YRX7pvx0RhA7evulkQz0cyaEPMf_wpaz0EU8AcnoT3kaHXt1uJJ4UjLF3z0R5oxMORn3hJAlhKw.mp4?...",
      "videoSdUrl": "https://video.fmlg11-1.fna.fbcdn.net/o1/v/t2/f2/m412/AQMddhKrjYyJ29AZws3WYFzy2UCdWdbt77GxCB-X7VBcW4FN3Lp_tR57jJJKJMOlqr0f1592k-7HVbts_lbo74P3iAj17THiNLY2hMumjw.mp4?...",
      "videoPreviewImageUrl": "https://scontent.fmlg11-1.fna.fbcdn.net/v/t39.35426-6/801045972_1465105502122307_1092039215951398992_n.jpg?..."
    }
  ],
  "extraLinks": [],
  "extraTexts": [],
  "adCategories": [],
  "byline": null,
  "spend": null,
  "currency": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedOrReachedCountries": [],
  "payerInfo": null,
  "containsAiGeneratedMedia": false,
  "containsSensitiveContent": false,
  "collationId": "1618301556302158",
  "collationCount": 2,
  "totalResults": 21663,
  "sourceUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all"
}
```

You can download the dataset in JSON, CSV, Excel, XML, or HTML, or access it through the Apify API.

### Notes

- Residential proxies are required to collect more than the first 30 ads of a search. Without them the Ad Library stops returning results after the first 30 ads.
- Only Ad Library search, advertiser page, and single ad URLs are supported. Other URLs, such as the Ad Library home page without a keyword or advertiser, are skipped.
- Ads that have several versions are returned one item per version. `collationId` and `collationCount` show which ads belong together.
- Spend, impressions, reach estimate, byline, and payer are only shown by the Ad Library for political and issue ads. For other ads they are `null`.
- Media links (images, videos) come from Meta's servers and expire after some time. Download the files soon after the run if you need to keep them.
- `totalResults` is the number of ads the Ad Library reports for your search, which is an estimate.

### Why use the Facebook Ads Library Scraper?

- ✅ **No login needed**: works with public data only, so there is no Facebook account to manage.
- 🎯 **Keeps your filters**: paste any Ad Library URL from your browser and get exactly what you see there.
- 🔎 **Three ways in**: search by keyword, scrape all ads of an advertiser, or fetch one ad by its URL.
- 🧹 **Clean data**: numbers are real numbers, dates use one standard format, and every carousel card and video is listed.
- 💸 **Pay for what you need**: set a result limit per URL or keyword and keep every run small and cheap.
- 🔄 **Ready for automation**: schedule runs, export to Google Sheets, or connect to Make, Zapier, and n8n.

### FAQ

#### How many ads can I scrape?

You can set any number in **Maximum number of ads**, or 0 for no limit. The actor keeps going until it reaches your limit or runs out of ads for that URL or keyword.

#### Do I need a Facebook account?

No. The actor only collects publicly available data from the Ad Library. You do not need to log in or provide any account details.

#### How do I scrape all ads of one advertiser?

Open the advertiser in the Ad Library, copy the URL of their ads page (it contains `view_all_page_id`), and paste it into **Ad Library URLs**.

#### Can I scrape data on a schedule?

Yes. Use Apify Schedules to run the actor every hour, day, or week, and get fresh ads automatically.

#### Why are some fields empty?

Not every ad shows every piece of information. When a field is not available in the Ad Library, it is returned as `null` or an empty list.

#### Can I request a new feature or filter?

Yes. Right now the actor supports Ad Library URLs, keywords, and the filters listed above. If you need other inputs, such as content language for keywords or extra EU transparency details, get in touch and they can be added.

#### Can I get a custom or private version?

Yes. The actor can be customized for your workflow, delivered as a private version, or a new scraper can be built for a different website. Use the contact details below.

***

**Need help or want a custom solution?**

- 📧 Email: aboo.script@gmail.com
- 🧩 More scrapers: [Apify profile](https://apify.com/aboo.script)

### Image Credit

Image credit: [Meta Ad Library](https://www.facebook.com/ads/library/)

# Actor input Schema

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

Meta Ad Library URLs: a keyword search, an advertiser page (view_all_page_id) or a single ad (?id=). All filters in the URL (country, active status, ad category, media type, platforms, languages, dates) are kept.

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

Keywords to search in the Ad Library. Each keyword is scraped separately with the filters below.

## `maxResults` (type: `integer`):

Maximum number of ads to scrape per Ad Library URL or keyword. Use 0 for no limit.

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

Two-letter country code where the ads ran (for example US, GB, DE), or ALL for every country. Applies to search keywords only; Ad Library URLs keep their own filters.

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

Only active ads, only inactive ads, or both. Applies to search keywords only.

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

Ad category to search in. Applies to search keywords only.

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

Only ads with this kind of media. Applies to search keywords only.

## `searchType` (type: `string`):

Match any of the words, or the exact phrase. Applies to search keywords only.

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

Only ads shown on these platforms. Leave empty for all platforms. Applies to search keywords only.

## `startDateFrom` (type: `string`):

Only ads that started running on or after this date (YYYY-MM-DD). Applies to search keywords only.

## `startDateTo` (type: `string`):

Only ads that started running on or before this date (YYYY-MM-DD). Applies to search keywords only.

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

Proxy servers used to reach the Ad Library.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all"
    }
  ],
  "searchQueries": [
    "running shoes"
  ],
  "maxResults": 5,
  "country": "ALL",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `overview` (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 = {
    "startUrls": [
        {
            "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all"
        }
    ],
    "searchQueries": [
        "running shoes"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("aboo.script/facebook-ads-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 = {
    "startUrls": [{ "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all" }],
    "searchQueries": ["running shoes"],
}

# Run the Actor and wait for it to finish
run = client.actor("aboo.script/facebook-ads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered&media_type=all"
    }
  ],
  "searchQueries": [
    "running shoes"
  ]
}' |
apify call aboo.script/facebook-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aboo.script/facebook-ads-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/5Q8c0hTvgZOQbg6n9/builds/3sIe0hl3aawc9fHCB/openapi.json