# Facebook Ads Library Scraper: Meta Ads by Keyword or Page (`zaiq/facebook-ads-library-scraper`) Actor

Ads from Meta's public Ad Library by keyword or advertiser in any country: text, images, videos, links, call to action, start date and days running, platforms; political ads with spend and impressions. No login. $1 per 1,000 ads.

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

## Pricing

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

## Facebook Ads Library Scraper: Meta Ads by Keyword or Page

Get the ads running (or that ran) on **Facebook, Instagram, Messenger, Threads and the Audience Network** from Meta's
public **Ad Library**: search by keyword, or give an advertiser's Facebook Page, username, Page id or name, in any
country. For each ad you get its text, images, videos, landing page, call to action, start date and how long it has
been running, the platforms it runs on, and the advertiser. Political and issue ads add **spend, impressions and who
paid**. No login, no cookies, no Facebook account.

**$1 per 1,000 ads.** Duplicates across your searches, ads filtered out by your keyword and failed searches are free.

### What you can do with it

- **Competitor ad research**: every ad a competitor is running right now, with the creatives and landing pages.
- **Creative inspiration**: what is running for a product or a niche ("air fryer", "running shoes"), sorted the way
  the Ad Library sorts it, most impressions first.
- **Long-running winners**: `daysRunning` shows how long each ad has been live; ads that run for months usually work.
- **Market and country checks**: the same search in the US, the UK, Germany, India or South Africa.
- **Political and issue ads**: spend and impression ranges, and who paid, for elections and causes.

### Input

```json
{
  "searchTerms": ["running shoes", "air fryer"],
  "advertisers": ["https://www.facebook.com/yourcompetitor", "Competitor Name", "123456789012345"],
  "country": "US",
  "activeStatus": "active",
  "maxAdsPerSearch": 200
}
```

- `searchTerms`: keywords the ads mention, one search per line. `exactPhrase` matches them as one phrase.
- `advertisers`: one per line, as a **Facebook Page link**, a **username**, a **Page id**, an **Ad Library link** with
  `view_all_page_id`, or a **name** (matched among the advertisers of the ads that mention it, in your country).
  `advertiserKeyword` keeps only an advertiser's ads that mention certain words.
- Filters: `country` (or `ALL`), `activeStatus` (`active`, `inactive`, `all`), `mediaType` (images, videos, memes),
  `platforms`, `language`, `politicalAdsOnly`, `shownFrom` and `shownTo` (ads shown in that period).
- `maxAdsPerSearch`: up to 10,000 per search term or advertiser.

### Output

One row per ad. An example (advertiser and links replaced):

```json
{
  "adId": "1433447338670685",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1433447338670685",
  "advertiser": "Example Store",
  "advertiserPageId": "100000000000000",
  "advertiserUrl": "https://www.facebook.com/examplestore/",
  "isActive": true,
  "startDate": "2026-09-10",
  "endDate": "2026-10-12",
  "daysRunning": 33,
  "platforms": ["facebook", "instagram", "messenger", "threads"],
  "format": "VIDEO",
  "text": "Get your beauty essentials 💄",
  "title": "Shop the range",
  "linkUrl": "https://www.example.com/",
  "ctaText": "Shop now",
  "images": ["https://scontent.xx.fbcdn.net/..."],
  "videos": [{ "hd": "https://video.xx.fbcdn.net/...", "sd": "https://video.xx.fbcdn.net/...", "preview": "https://..." }],
  "cards": null,
  "adsUsingThisCreative": 4,
  "spend": null,
  "impressions": null,
  "searchType": "advertiser",
  "searchQuery": "examplestore",
  "country": "ZA",
  "scrapedAt": "2026-10-12T12:48:00Z"
}
```

- `format`: IMAGE, VIDEO, CAROUSEL, DPA (catalogue ads), DCO (dynamic creative) and so on. Carousel and catalogue ads
  list their items in `cards`.
- `adsUsingThisCreative`: how many ads share this creative in the Ad Library.
- Political and issue ads add `spend` and `impressions` ranges, `currency`, `paidFor` and `countries`.
- The key-value store record `SUMMARY` lists every search, the advertiser it resolved to, its ad count and any notes
  (for example, an advertiser that shows no ads in the country you chose).

### Pricing

- **$0.001 per ad** ($1 per 1,000 ads), lower on Apify's Scale and Business plans (Store discounts).
- **Free**: an ad already returned by another of your searches, ads left out by `advertiserKeyword`, and searches that
  fail or find nothing.
- Plus Apify's standard run start fee. Your spending limit for the run is respected.

### Use it from code, automations and AI agents

- **API**: `POST https://api.apify.com/v2/acts/zaiq~facebook-ads-library-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN`
  with the input as JSON returns the ads in one call. The API tab has Python, JavaScript and cURL examples.
- **Python** (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("zaiq/facebook-ads-library-scraper").call(run_input={
    "advertisers": ["https://www.facebook.com/yourcompetitor"],
    "country": "US",
    "maxAdsPerSearch": 500,
})
for ad in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(ad["startDate"], ad["daysRunning"], ad["format"], ad["text"])
```

- **No code**: schedule a weekly run to watch competitors' new ads, send rows to Google Sheets, Zapier, Make or n8n
  from the Integrations tab, and get a webhook when a run finishes.
- **AI agents (MCP)**: `https://mcp.apify.com?tools=zaiq/facebook-ads-library-scraper` adds it as a tool to Claude,
  Cursor or any MCP client.

### FAQ

**Do I need a Facebook account or an access token?** No. It reads the same public Ad Library that anyone can open
without logging in. It does not use Meta's Ad Library API, which needs a verified developer account and covers only
political and issue ads in most countries.

**Which countries?** Any country the Ad Library covers; pick one in `country`, or `ALL`.

**How are ads ordered?** Keyword searches come back the way the Ad Library sorts them: most impressions first. An
advertiser's ads come back newest first.

**Why did an advertiser return no ads?** It may not advertise in the country you chose, or only have stopped ads: try
`activeStatus` `all` or another country. `SUMMARY` says which Page the advertiser resolved to.

**What about ads that stopped running?** Set `activeStatus` to `inactive` or `all`. Meta keeps most ads in the library
for a limited time; political and issue ads for seven years.

### Limits

- About 10 ads per page from the Ad Library; a 1,000-ad search takes a couple of minutes.
- Up to 6 searches at a time.

# Actor input Schema

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

Keywords the ads mention, one search per line, as you would type them into the Ad Library.

## `advertisers` (type: `array`):

One advertiser per line: a Facebook Page link (https://www.facebook.com/brand), a username, a Page id, an Ad Library link with view_all_page_id, or a name. Returns that advertiser's ads.

## `advertiserKeyword` (type: `string`):

Optional: with advertisers, keep only their ads whose text mentions these words (the others are left out and not charged).

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

Where the ads were shown. ALL = every country.

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

Active: running now. Inactive: stopped. All: both.

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

Only ads with this kind of media.

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

Only ads shown on these. Empty = all platforms.

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

Match the words in order, as one phrase.

## `politicalAdsOnly` (type: `boolean`):

Only ads about social issues, elections or politics: these come with spend, impressions and who paid.

## `language` (type: `string`):

Only ads in this language, as a two-letter code (en, es, de, af...). Empty = any.

## `shownFrom` (type: `string`):

Only ads shown on or after this day.

## `shownTo` (type: `string`):

Only ads shown on or before this day.

## `maxAdsPerSearch` (type: `integer`):

How many ads at most for each search term or advertiser.

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

How many searches run at the same time.

## Actor input object example

```json
{
  "searchTerms": [
    "running shoes"
  ],
  "country": "US",
  "activeStatus": "active",
  "mediaType": "all",
  "exactPhrase": false,
  "politicalAdsOnly": false,
  "maxAdsPerSearch": 100,
  "maxConcurrency": 3
}
```

# Actor output Schema

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

Dataset: one row per ad.

## `summary` (type: `string`):

Each search and what it returned.

# 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"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zaiq/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"] }

# Run the Actor and wait for it to finish
run = client.actor("zaiq/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"
  ]
}' |
apify call zaiq/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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