# Facebook Ads Library Scraper (`mighty_monk/facebook-ads-library-scraper`) Actor

Scrape Meta (Facebook) Ad Library for competitor ads by search terms. Extract ad text, CTAs, media, platforms, and dates for competitive intelligence and GTM agents.

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

## Pricing

from $3.00 / 1,000 ad scrapeds

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/platform/actors/running/actors-in-store#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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

### What does Facebook Ads Library Scraper do?

**Facebook Ads Library Scraper** extracts **public competitor ads** from the [Meta Ad Library](https://www.facebook.com/ads/library/) by search term and country. It returns structured fields such as ad text, CTA, platforms, media URLs, page info, and library links — ready for **daily competitive intel**, GTM agents, and creative research workflows.

Run it on the **Apify platform** for scheduling, API access, proxy rotation, monitoring, and integrations with Make, Zapier, n8n, and your own agents.

### Why use Facebook Ads Library Scraper?

- **Competitive intelligence** — Monitor what rivals run on Facebook and Instagram without a Meta Business login for public library data.
- **Creative research** — Collect ad copy, CTAs, and creative media URLs for inspiration and messaging analysis.
- **GTM & product agents** — Feed structured ad datasets into AI agents that track market positioning daily.
- **Multi-market coverage** — Search the same brand across countries (`US`, `GB`, `DE`, …) in one run.
- **Automation-ready** — JSON dataset export, pay-per-event pricing, and Apify schedules.

### How to use Facebook Ads Library Scraper

1. Open the Actor in Apify Console and click **Try for free**.
2. Enter one or more **search terms** (brand name, product keyword, or Page name).
3. Optionally set **countries**, **ad type** (all / political / housing), and **max ads**.
4. Keep **proxy** enabled (residential recommended) for reliable Meta access.
5. Click **Start** and download results as JSON, CSV, Excel, or HTML.

### Input

Configure inputs in the **Input** tab. Main fields:

| Field | Type | Description |
| --- | --- | --- |
| `searchTerms` | string[] | Keywords / brand names to search (required) |
| `countries` | string[] | ISO country codes (default `["US"]`). Use `ALL` for unfiltered |
| `adType` | string | `all`, `political`, or `housing` |
| `maxAds` | integer | Cap on unique ads (0 = unlimited) |
| `maxConcurrency` | integer | Parallel requests (keep low, default 2) |
| `maxRequestRetries` | integer | Retries for failed / blocked pages |
| `requestDelayMs` | integer | Delay between requests to reduce blocks |
| `proxyConfiguration` | object | Apify Proxy settings |

Example:

```json
{
    "searchTerms": ["Nike", "Shopify"],
    "countries": ["US"],
    "adType": "all",
    "maxAds": 20,
    "proxyConfiguration": { "useApifyProxy": true }
}
````

### Output

Each dataset item is one ad (or a search-level error row). You can download the dataset in **JSON, HTML, CSV, or Excel**.

```json
{
    "adId": "123456789012345",
    "pageName": "Nike",
    "pageId": "987654321",
    "pageUrl": "https://www.facebook.com/nike",
    "adText": "Just Do It. New collection available now.",
    "ctaText": "Shop Now",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": null,
    "platforms": ["FACEBOOK", "INSTAGRAM"],
    "mediaUrls": ["https://scontent.xx.fbcdn.net/v/nike-orig.jpg"],
    "adSnapshotUrl": "https://www.facebook.com/ads/library/?id=123456789012345",
    "libraryUrl": "https://www.facebook.com/ads/library/?id=123456789012345",
    "status": "active",
    "searchTerm": "Nike",
    "country": "US",
    "scrapedAt": "2026-07-20T12:00:00.000Z",
    "error": null
}
```

A run summary is stored in the key-value store under `OUTPUT`.

### Data table

| Field | Description |
| --- | --- |
| `adId` | Meta ad archive ID |
| `pageName` | Advertising Page name |
| `pageId` | Facebook Page ID |
| `pageUrl` | Page URL when available |
| `adText` | Primary ad body / creative text |
| `ctaText` | Call-to-action label |
| `startDate` | Delivery start (ISO) |
| `endDate` | Delivery end (ISO) when present |
| `platforms` | e.g. FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE\_NETWORK |
| `mediaUrls` | Image / video URLs from the creative snapshot |
| `adSnapshotUrl` | Snapshot / deep link for the ad |
| `libraryUrl` | Ad Library URL for the ad |
| `status` | `active` / `inactive` when detectable |
| `searchTerm` | Query that produced the ad |
| `country` | Country filter used |
| `scrapedAt` | ISO timestamp |
| `error` | Error message when the row is a failure record |

### Pricing / Cost estimation

How much does it cost to scrape Facebook Ads Library?

This Actor uses **pay-per-event (PPE)** pricing at about **$0.003 per ad** written to the default dataset (`apify-default-dataset-item`), plus a tiny actor-start fee. Approximate examples:

| Ads scraped | Est. event cost |
| ---: | ---: |
| 100 | ~$0.30 |
| 1,000 | ~$3.00 |
| 10,000 | ~$30.00 |

Platform compute and proxy (especially residential) are billed separately by Apify. Use `maxAds` to cap spend.

### Tips and advanced options

- Prefer **residential proxies** — Meta often blocks bare datacenter IPs on Ad Library.
- Keep **maxConcurrency** at 1–3 and **requestDelayMs** ≥ 1500 for fewer checkpoints.
- Start with a known brand (`Nike`, `Apple`) and `maxAds: 10` to validate connectivity.
- The Actor uses **Cheerio** with multi-strategy parsing of embedded JSON (`ad_archive_id`, Relay / ServerJS blobs, regex fallback). Heavily JS-gated responses may return fewer fields; retries and proxies improve success.
- Schedule daily runs for continuous competitor monitoring.

### FAQ, disclaimers, and support

**Is scraping the Ad Library legal?**\
Meta publishes the Ad Library for transparency. You are responsible for complying with Meta’s Terms, applicable laws, and your own use-case policy. This Actor only targets **public** library pages.

**Why are some fields null?**\
Meta’s HTML varies by region and experiment. The scraper fills what it can from embedded JSON and falls back gracefully.

**Why zero ads?**\
Possible causes: captcha/checkpoint, no matching active ads, or temporary blocks. Check the `error` field and enable residential proxy.

**Support**\
Open an issue on the Actor’s **Issues** tab in Apify Console. Custom enterprise scrapers and agents are available on request.

# Actor input Schema

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

Keywords, brand names, or Page names to search in the Meta Ad Library (e.g. Nike, Shopify, crypto wallet).

## `countries` (type: `array`):

ISO country codes to filter ads (e.g. US, GB, DE). Use ALL for no country filter. Defaults to US when empty.

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

Meta Ad Library ad category filter.

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

Maximum number of unique ads to collect across all search terms and countries (0 = unlimited, use with care).

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

Maximum parallel HTTP requests. Keep low (1–3) — Meta aggressively rate-limits Ad Library traffic.

## `maxRequestRetries` (type: `integer`):

How many times to retry a failed or blocked request.

## `requestDelayMs` (type: `integer`):

Base delay before each request (plus small random jitter) to reduce blocks.

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

Apify Proxy settings. Strongly recommended — Meta often blocks bare datacenter IPs. Prefer RESIDENTIAL for production.

## Actor input object example

```json
{
  "searchTerms": [
    "Nike",
    "Shopify"
  ],
  "countries": [
    "US"
  ],
  "adType": "all",
  "maxAds": 50,
  "maxConcurrency": 2,
  "maxRequestRetries": 3,
  "requestDelayMs": 2000,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (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": [
        "Nike",
        "Shopify"
    ],
    "countries": [
        "US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("mighty_monk/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": [
        "Nike",
        "Shopify",
    ],
    "countries": ["US"],
}

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": [
    "Nike",
    "Shopify"
  ],
  "countries": [
    "US"
  ]
}' |
apify call mighty_monk/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=mighty_monk/facebook-ads-library-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Facebook Ads Library Scraper",
        "description": "Scrape Meta (Facebook) Ad Library for competitor ads by search terms. Extract ad text, CTAs, media, platforms, and dates for competitive intelligence and GTM agents.",
        "version": "1.0",
        "x-build-id": "P3a3oTCk6g19XXL5D"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/mighty_monk~facebook-ads-library-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-mighty_monk-facebook-ads-library-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/mighty_monk~facebook-ads-library-scraper/runs": {
            "post": {
                "operationId": "runs-sync-mighty_monk-facebook-ads-library-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/mighty_monk~facebook-ads-library-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-mighty_monk-facebook-ads-library-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "searchTerms"
                ],
                "properties": {
                    "searchTerms": {
                        "title": "Search terms",
                        "type": "array",
                        "description": "Keywords, brand names, or Page names to search in the Meta Ad Library (e.g. Nike, Shopify, crypto wallet).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "countries": {
                        "title": "Countries",
                        "type": "array",
                        "description": "ISO country codes to filter ads (e.g. US, GB, DE). Use ALL for no country filter. Defaults to US when empty.",
                        "default": [
                            "US"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "adType": {
                        "title": "Ad type",
                        "enum": [
                            "all",
                            "political",
                            "housing"
                        ],
                        "type": "string",
                        "description": "Meta Ad Library ad category filter.",
                        "default": "all"
                    },
                    "maxAds": {
                        "title": "Max ads",
                        "minimum": 0,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Maximum number of unique ads to collect across all search terms and countries (0 = unlimited, use with care).",
                        "default": 50
                    },
                    "maxConcurrency": {
                        "title": "Max concurrency",
                        "minimum": 1,
                        "maximum": 20,
                        "type": "integer",
                        "description": "Maximum parallel HTTP requests. Keep low (1–3) — Meta aggressively rate-limits Ad Library traffic.",
                        "default": 2
                    },
                    "maxRequestRetries": {
                        "title": "Max request retries",
                        "minimum": 0,
                        "maximum": 10,
                        "type": "integer",
                        "description": "How many times to retry a failed or blocked request.",
                        "default": 3
                    },
                    "requestDelayMs": {
                        "title": "Request delay (ms)",
                        "minimum": 0,
                        "maximum": 60000,
                        "type": "integer",
                        "description": "Base delay before each request (plus small random jitter) to reduce blocks.",
                        "default": 2000
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Apify Proxy settings. Strongly recommended — Meta often blocks bare datacenter IPs. Prefer RESIDENTIAL for production.",
                        "default": {
                            "useApifyProxy": true
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```