# Facebook Ads Library Scraper (`intelscrape/facebook-scraper`) Actor

Facebook Ads Library scraper for creatives and copy. Competitor ad research. Pay per result.

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

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Facebook Ads Library Scraper – Ad Creatives & Copy

![Actor Banner](https://api.apify.com/v2/key-value-stores/PyvJzfQg02FD3RYhd/records/facebook-scraper-banner.png)

> 🇨🇳 **中文简介 (Chinese — China & Singapore):**
> 要研究竞品 Facebook / Meta 广告素材与文案？从 Ads Library 抓取创意、文案与投放相关公开信号，帮助复盘投放与创意迭代。按结果计费，无需自建采集栈——适合中国与新加坡跨境增长、代理与品牌团队。现在试跑，把广告情报导出到表格或 Claude / Cursor 分析。

> 🇸🇬 **Ringkasan Melayu (Singapore):**
> Nak kaji kreatif dan salinan iklan pesaing di Facebook/Meta Ads Library? Scrap kreatif, copy dan isyarat kempen awam untuk risikan dan iterasi iklan. Bayar per hasil, tiada stack crawler sendiri. Ideal untuk growth, agensi dan jenama di Singapura serta China. Cuba di Apify dan eksport intel iklan.

#### 🤖 NEW: Connect This To Your AI!

Want to use this scraper directly inside Claude, Cursor, or ChatGPT? Check out **[Skip Trace MCP Server](https://apify.com/intelscrape/skip--trace)**. Let your AI research Meta Ads Library creatives. Combined IntelScrape agents over Model Context Protocol — autonomous leads, enrichment, outreach prep.

#### 🏆 Featured Bots by IntelScrape

1. **[Facebook Ads Library Scraper](https://apify.com/intelscrape/facebook-scraper)** — Ad Creatives & Copy Research
2. **[Facebook Marketplace Deal Radar](https://apify.com/intelscrape/facebook-marketplace-deal-radar)** — Underpriced Local Deals
3. **[Skip Trace PRO](https://apify.com/intelscrape/skip-trace-pro)** — Name, Address, Phone & Email People Lookup
4. **[TruePeopleSearch Scraper](https://apify.com/intelscrape/truepeoplesearch-scraper)** — Phone & Email Matches
5. **[TikTok Scraper](https://apify.com/intelscrape/tiktok-scraper)** — Emails & Influencer Leads
6. **[Amazon Product Review Scraper](https://apify.com/intelscrape/amazon-product-review-scraper)** — Deep E-commerce & Review Extraction
7. **[Building Permit Scraper](https://apify.com/intelscrape/building-permit-scraper)** — US Cities Open Data
8. **[Google Maps No-Website Leads](https://apify.com/intelscrape/website-Leads)** — Local Businesses Without a Website
9. **[UCC Lien Scraper](https://apify.com/intelscrape/ucc-lien-scraper)** — Florida & New Jersey Filings

> **Nice — next step:** Hunting Marketplace deals from the same Meta ecosystem? Run **[Facebook Marketplace Deal Radar](https://apify.com/intelscrape/facebook-marketplace-deal-radar)**. Need advertiser / page-owner phones? **[Skip Trace PRO](https://apify.com/intelscrape/skip-trace-pro)**. Continue in Claude / Cursor → **[Skip Trace MCP](https://apify.com/intelscrape/skip--trace)**.

***

⚡ **Use this Actor in n8n — no code**

1. Add the official **Apify** node in n8n.
2. Connect your Apify API token.
3. Run Actor ID: `IntelScrape/facebook-scraper`.

***

The most reliable, bypass-proof Meta Ad Library scraper on the market. Extracts full ad copy, pristine image/video URLs, and metadata by directly intercepting Facebook's internal APIs—completely sidestepping fragile HTML scraping.

### Days Running (winning-ad signal)

Each ad includes **Days Running** — how long it has been live since Start Date. Long-running ads are a strong competitor-creative signal (brilliant\_gum parity).

### Media & date filters

Use **Media type** plus optional **Min/Max start date** (YYYY-MM-DD) to narrow the Ads Library the same way Meta UI filters work.

### 🚀 Why This Scraper is Different (and Better)

Most Facebook scrapers on Apify suffer from two fatal flaws: they crash on 403 WAF blocks, or they break when Facebook changes their CSS classes, returning zero results.

**We solved both:**

1. **Total WAF Immunity:** We mimic human clicks from the Facebook homepage to generate perfect headers and session tokens. Even if Meta's frontend blocks the HTML load, our scraper successfully intercepts the raw JSON GraphQL payloads happening behind the scenes.
2. **Zero DOM Fragility:** Because we extract directly from Meta's structured backend JSON responses, this scraper is immune to Facebook's daily UI/CSS updates.
3. **Boardroom-Ready CSV Exports:** We don't give you messy JSON arrays. We automatically format Unix timestamps into human-readable dates, clean up the ad copy formatting, and extract pristine single URLs for Primary Images and Videos so they paste perfectly into Excel and Google Sheets.

### 💡 How to Search (Crucial for 5-Star Data)

The #1 mistake users make is treating the Facebook Ad Library like Google Maps. The search box only matches the **ad text** and the **advertiser's name**. It does NOT match location or targeting data.

**If you put a city or county in the search term, you are almost guaranteed 0 results.** (e.g., searching `"plumber dallas"` will fail, because advertisers rarely write "dallas" in their ad copy).

Here are the 3 ways to search correctly:

1. **Spy on ONE competitor (Best Results):** Type their exact Facebook Page name (e.g., `Gymshark` or `Premier Building Solutions`). This returns that advertiser's entire ad playbook.
2. **Scan a whole category for ideas:** Use a broad product term, no geography (e.g., `metal buildings`, `storage sheds`, `CRM software`, `shapewear`).
3. **Find LOCAL competitors:** Search broad (e.g., `metal buildings`), export the CSV, and then use Excel to filter the `Ad Copy` column for your area code or nearby town names. The location is sitting *in the data*, not in the search query.

### SoftCTA (dataset)

Each successful run also pushes an **`ads-batch-summary`** row with a `softCta` funnel to Marketplace Deal Radar, Contact Info, Maps Email, and Skip Trace PRO.

### 📊 Output Format

The output is perfectly formatted for marketers:

- `Ad Copy`: Full, clean text of the ad.
- `Ad Library URL`: Direct, clickable link to view the live ad in your browser.
- `Advertiser`: The Facebook Page running the ad.
- `Library ID`: The unique Meta Ad ID.
- `Primary Image URL`: High-res JPG/PNG link.
- `Primary Video URL`: Raw MP4 video link.
- `Publisher Platforms`: Where the ad runs (e.g., FACEBOOK, INSTAGRAM).
- `Start Date`: Human-readable date format (YYYY-MM-DD).
- `Status`: Active or Inactive.

### ⚙️ Configuration

- **Search Terms:** A list of keywords or advertiser names.
- **Country:** Target country code (Default: US).
- **Max Ads Per Search:** Deep infinite scroll (Default: 100).
- **Active Status:** Filter by Active/Inactive ads.

### Pricing (PPE)

| Event | Price |
| :--- | ---: |
| Actor start | **$0.0005** |
| Ad result (`apify-default-dataset-item`) | **$0.002** |
| Media asset delivered (`media-asset`) | **$0.001** |

`media-asset` is charged **once per ad** when a **Primary Image URL** and/or **Primary Video URL** is delivered (including demoMode fixtures with sample media URLs). Soft CTA: Marketplace deals → **[Deal Radar](https://apify.com/intelscrape/facebook-marketplace-deal-radar)**; owner phones → **[Skip Trace PRO](https://apify.com/intelscrape/skip-trace-pro)**.

Enjoy the most bulletproof Facebook Ad intelligence tool available!

# Actor input Schema

## `searchMode` (type: `string`):

Choose how you want to search.

## `searchInputs` (type: `array`):

❌ Never type a city or state here — it returns 0 results. Set location in the Country field below.

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

Country code to search in.

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

Maximum number of ads to extract per search term.

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

Filter by active or inactive ads.

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

Filter Ads Library results by creative media (igolaizola/Meta parity). Wired to Meta media\_type URL param.

## `minDate` (type: `string`):

Only keep ads that started on/after this date. Also passed to Meta start\_date\[min]. Leave empty for no lower bound.

## `maxDate` (type: `string`):

Only keep ads that started on/before this date. Also passed to Meta start\_date\[max]. Leave empty for no upper bound.

## `filterSpamAds` (type: `boolean`):

In Keyword mode, drop 'story ads' (serialized fiction novels) that spam broad keywords by filtering out ad copy over 3000 characters. Does not apply to Competitor or URL modes.

## `autoBroaden` (type: `boolean`):

If a specific search returns 0 results, automatically shorten the keywords to find related ads. When enabled, broadened results will be labeled 'Auto-Broadened: TRUE' so you know the query was shortened.

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

Select the proxies to be used. Residential proxies are highly recommended to bypass Meta's anti-bot systems.

## `demoMode` (type: `boolean`):

Push 3 fixture ads and skip live Meta scrape. Use for Console try-runs. Live 0-ad runs hard-fail instead of soft SUCCEEDED×0.

## Actor input object example

```json
{
  "searchMode": "keyword",
  "searchInputs": [
    "metal buildings"
  ],
  "country": "US",
  "maxAdsPerSearch": 100,
  "activeStatus": "all",
  "mediaType": "all",
  "minDate": "",
  "maxDate": "",
  "filterSpamAds": true,
  "autoBroaden": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "demoMode": false
}
```

# Actor output Schema

## `Search Term` (type: `string`):

The search term used

## `Auto-Broadened` (type: `string`):

Indicates if the query was broadened

## `Library ID` (type: `string`):

Meta Ad Library ID

## `Advertiser` (type: `string`):

The Facebook Page name

## `Status` (type: `string`):

Active or Inactive status

## `Start Date` (type: `string`):

The date the ad started running

## `Ad Copy Length` (type: `string`):

Character count of the ad copy

## `Ad Copy` (type: `string`):

The main text of the ad

## `Primary Image URL` (type: `string`):

URL to the ad's main image

## `Primary Video URL` (type: `string`):

URL to the ad's main video

## `Publisher Platforms` (type: `string`):

Platforms the ad runs on (Facebook, Instagram)

## `Ad Library URL` (type: `string`):

Direct link to the ad in Meta Ad Library

# 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 = {};

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

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

```

## MCP server setup

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