# Facebook Ads Library Scraper for Marketers (`tenfoldfleet/facebook-ads-library-scraper`) Actor

Get the ads any brand or keyword runs on Facebook and Instagram from the Meta Ad Library: advertiser, ad copy, CTA, landing page URL, start date, days running, platforms, ad variations and an ads-per-advertiser summary. $6 per 1,000 ads; empty searches are free.

- **URL**: https://apify.com/tenfoldfleet/facebook-ads-library-scraper.md
- **Developed by:** [Tenfold Fleet](https://apify.com/tenfoldfleet) (community)
- **Categories:** Social media, Agents, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 ads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

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

*Not affiliated with, endorsed by or sponsored by Meta Platforms, Inc. Facebook and Instagram are trademarks of Meta.*

### What does Facebook Ads Library Scraper for Marketers do?

**Facebook Ads Library Scraper for Marketers** collects the ads that brands run on **Facebook, Instagram, Messenger, Threads and Audience Network** from the public **Meta Ad Library** (facebook.com/ads/library). Type a **keyword** ("running shoes"), an **advertiser Page ID** or paste an **Ad Library search link**, pick a country, and you get one clean row per ad with the fields a marketer looks at first: **advertiser, ad copy, headline, call to action, landing page URL, start date, days running, platforms and number of ad variations**.

It also writes an **ads-per-advertiser summary** for every search: who is advertising on your keyword, how many ads each brand runs, how many variations they test and their longest-running ad. Use it as a **Facebook Ads Library API**: call it from the Apify API, a schedule, Make, Zapier or an AI agent. No Facebook account, login or cookies are needed.

### Why use it?

- **Competitor ad research**: see every ad a competitor runs right now, with the copy, offer and landing page.
- **Find winning ads**: ads that have run for many days, or that the advertiser tests in many variations, usually perform. Sort by `daysRunning` or `collationCount`.
- **Market mapping**: search a niche keyword and read the summary to see which brands spend on Meta ads in it.
- **Creative swipe files**: collect image and video URLs, headlines and CTAs for inspiration.
- **Political and issue ads**: spend ranges, impressions, currency and who paid for the ad.
- **Monitoring**: schedule it weekly on your competitors' Page IDs and compare `adArchiveId` values between runs.

Dynamic creative and catalog ads often show `{{product.name}}` placeholders in the Ad Library data. This Actor fills `bodyText`, `title`, `linkUrl` and `ctaText` from the ad's first real card instead, so the copy you get is the copy people saw.

### What data can it extract?

| Field | Description |
|---|---|
| `pageName`, `pageId`, `pageProfileUrl`, `pageLikeCount` | The advertiser |
| `bodyText`, `title`, `linkDescription` | Ad copy, headline and link description |
| `ctaText`, `ctaType` | Call to action ("Shop now", `SHOP_NOW`) |
| `linkUrl`, `displayUrl` | Landing page URL and the domain shown on the ad |
| `startDate`, `endDate`, `daysRunning`, `isActive` | When the ad started, stopped and how many days it has run |
| `platforms` | facebook, instagram, messenger, threads, audience_network, whatsapp |
| `collationCount` | How many variations of this ad the advertiser runs |
| `displayFormat` | IMAGE, VIDEO, CAROUSEL, DCO (dynamic creative) or DPA (catalog) |
| `imageUrls`, `videoUrls`, `videoPreviewImageUrls`, `cards` | Creative media and carousel cards |
| `spend`, `spendMin`, `spendMax`, `impressions`, `impressionsMin`, `impressionsMax`, `currency`, `paidForBy` | Shown for political and issue ads |
| `adArchiveId`, `adLibraryUrl` | Ad ID and a direct link to the ad in the Ad Library |
| `query`, `queryType`, `country` | Which search found the ad |

### How to scrape the Facebook Ads Library

1. Add one or more **search terms**, **advertiser Page IDs** or **Ad Library URLs**.
2. Choose a **country** (US by default, or ALL), **active status**, **ad category** and **media type**. Optionally set a date range.
3. Set **Max ads per query** (default 100, up to 5,000).
4. Click **Start**. Download the ads as JSON, CSV or Excel, or read them through the API. The ads-per-advertiser summary is in the run's key-value store under `SUMMARY`.

### How much does it cost?

Pay per result: **$6 per 1,000 ads ($0.006 per ad)**, plus a tiny $0.00005 start fee per run. Proxy and compute costs are included. Searches that find no ads, invalid input and failed searches return a free row and cost nothing. Set a maximum cost per run in Apify and the Actor stops cleanly when it is reached. On the Apify Free plan, the $5 monthly credit covers about 800 ads.

### Input

```json
{
    "searchTerms": ["running shoes"],
    "pageIds": ["15087023444"],
    "country": "US",
    "activeStatus": "active",
    "adType": "all",
    "mediaType": "all",
    "maxAdsPerQuery": 100
}
```

### Output

```json
{
    "pageName": "Example Running Co",
    "bodyText": "Our lightest trainer yet. Free returns for 60 days.",
    "title": "Meet the Cloud Runner 2",
    "ctaText": "Shop now",
    "linkUrl": "https://example.com/cloud-runner-2",
    "startDate": "2026-08-17",
    "daysRunning": 68,
    "isActive": true,
    "platforms": ["facebook", "instagram"],
    "collationCount": 3,
    "displayFormat": "VIDEO",
    "adArchiveId": "1234567890123456",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1234567890123456",
    "pageId": "100000000000000",
    "imageUrls": [],
    "videoUrls": ["https://video.xx.fbcdn.net/..."],
    "query": "running shoes",
    "country": "US"
}
```

A search with no ads returns `{"query": "...", "adsFound": 0}` and is not charged.

### Tips

- **Page ID**: open the advertiser in the Ad Library; the number after `view_all_page_id=` in the address bar is the Page ID. You can paste that whole link into **Advertiser Page IDs**.
- **Exact phrase** matches the whole phrase; without it, an ad that contains any of the words can match.
- Keyword results come in the order the Ad Library itself shows them, so the first ads you get are the ones a visitor sees first.
- Media URLs from Meta expire after a few days. Download the creatives you want to keep soon after the run.
- The proxy setting defaults to residential, which is included in the price. Datacenter proxies only get the first 30 ads of a search.
- **Parallel queries** opens one browser session per parallel query, and only when there are at least 3 queries for each session.

### Use it with AI agents (MCP)

Give Claude, ChatGPT, Cursor or any MCP client this Actor as a tool through Apify's MCP server: add `https://mcp.apify.com?tools=tenfoldfleet/facebook-ads-library-scraper` as a remote MCP server and sign in with your Apify account. The agent fills in the input, runs the Actor and reads the ads itself; you pay the same per-ad price as a normal run.

### FAQ

#### Do I need a Facebook account?

No. The Meta Ad Library is public, and the Actor reads it the way a logged-out visitor does. It never logs in and uses no account cookies.

#### Can I get every ad of one brand?

Yes. Put the brand's Page ID in **Advertiser Page IDs**, set **Active status** to "Active and inactive ads" and **Country** to ALL.

#### Why do spend and impressions appear only on some ads?

Meta publishes spend, impressions and the payer only for ads about social issues, elections or politics. Set **Ad category** to "Issues, elections or politics" to search those ads.

#### How many ads can I get per search?

Up to 5,000 per query. Popular keywords have tens of thousands of ads; the summary shows the total that Meta reports. After the first 30 or so, Meta sends ads 10 at a time, so one query collects roughly 100 to 150 ads a minute. For several thousand ads per query, raise the run timeout or split the work over a few runs.

### Disclaimer

This Actor is not affiliated with or endorsed by Meta. It collects only publicly available advertising data from the Meta Ad Library and does not log in. Make sure your use of the data complies with Meta's terms and the laws that apply to you.

# Actor input Schema

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

Keywords to search in the Meta Ad Library, one per line (a product, a niche, a brand or a phrase). Each term is one query.

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

Facebook Page IDs of advertisers, to get every ad one brand runs. The ID is the number after view_all_page_id= in an Ad Library link (you can paste that whole link here too).

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

Search links copied from https://www.facebook.com/ads/library/ after you set filters there. The filters in the link are used as they are.

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

Two-letter country code of the market where the ads ran (US, GB, DE, FR, AU, BR...), or ALL for every country.

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

Only ads running now, only ads that stopped, or both.

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

All ads, or only ads about social issues, elections or politics (these include spend, impressions and who paid).

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

Filter by the creative's media.

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

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

## `startDate` (type: `string`):

Optional. Only ads that delivered impressions on or after this date (YYYY-MM-DD).

## `endDate` (type: `string`):

Optional. Only ads that delivered impressions on or before this date (YYYY-MM-DD).

## `maxAdsPerQuery` (type: `integer`):

Stop each search term, Page or URL after this many ads (up to 5,000). Each ad returned is one charged result. On the Apify Free plan the run also stops when your monthly free credit runs out.

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

How many queries to load at the same time. Keep it low: Meta slows down sessions that load too fast.

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

Residential proxy is the default and the cost is included in the price per ad. Datacenter IPs only get the first 30 ads of each query before Meta rate-limits them.

## Actor input object example

```json
{
  "searchTerms": [
    "running shoes"
  ],
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "exactPhrase": false,
  "maxAdsPerQuery": 100,
  "maxConcurrency": 2,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (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"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

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

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

```

## MCP server setup

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