# Meta Ads Library Scraper - Fast & Reliable (`seeb/facebook-ads-library-scraper`) Actor

Scrape public Meta/Facebook ads by keyword, copied Ads Library URL, Facebook Page ID, or Ad Library ID. Extract ad text, CTA, platform, creative-format, advertiser, and metadata signals with proxy controls and delivered-row billing.

- **URL**: https://apify.com/seeb/facebook-ads-library-scraper.md
- **Developed by:** [Techionik](https://apify.com/seeb) (community)
- **Categories:** Social media, Lead generation, Automation
- **Stats:** 7 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.75 / 1,000 ad rows

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/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.

- **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

## Meta Ads Library Scraper - Fast & Reliable

Scrape public Meta ads in seconds by copied Ads Library URL, keyword, Facebook Page ID, or Ad Library ID. Get structured ad copy, advertiser, CTA, ad status, start date, placement signals, creative-format signals, direct ad URL, and change-tracking rows for growth teams, agencies, and competitive research.

![Meta Ads Library Scraper hero](./assets/hero.svg)

### Built For

- Competitor ad research across Facebook, Instagram, Messenger, WhatsApp, Threads, and Audience Network signals.
- Creative research for hooks, offers, CTAs, landing-page angles, and campaign messaging.
- Agency lead research by brand, page, niche, product, or keyword.
- Scheduled checks for new and updated ads without paying for blocked or empty sources.

### Search Modes

- `targetUrl`: paste the full Meta Ads Library URL copied from your browser. This takes priority over all other filters.
- `searchQuery`: search by brand, competitor, product, niche, or offer.
- `searchQueries`: run multiple keywords in one job.
- `pageId`: collect ads from a specific Facebook Page ID.
- `adId`: check one specific Meta Ad Library ID.
- `adLibraryUrls`: run multiple advanced Ads Library URLs in one job.

### Filters And Controls

- Country, ad status, ad type, media type, targeted-country mode, content language, sort mode, and sort direction.
- `maxResults` controls the maximum delivered ad rows.
- `maxConcurrency` controls speed for multiple keywords or URLs.
- `requestHandlerTimeoutSecs` and `maxRunMinutes` stop stalled sessions cleanly.
- `monitorChanges` and `onlyChanges` support scheduled new-ad and updated-ad workflows.

### Data Delivered

- `libraryId`, `pageName`, `adStatus`, `startedRunning`, `platforms`, `cta`, `creativeFormat`, and `adText`.
- Direct `adUrl`, original `sourceUrl`, `searchQuery`, `pageId`, requested ad ID, and scrape timestamp.
- `dataQualityScore` and `signalSummary` so rows are easier to sort, review, and export.
- Optional raw ad text for audit/debug workflows.
- Change rows such as `new_ad` and `updated_ad` when change detection is enabled.

### Proxy Strategy

Meta can limit direct browser sessions. Proxy quality is often the difference between a thin sample and a useful ad dataset. For serious runs, use `proxyUrl` with a reliable residential or managed proxy. In the input form, this appears as `Your proxy URL - recommended for highest fill rate`. The actor also supports Apify proxy modes when no custom proxy URL is provided.

- `none`: cheapest mode for quick checks.
- `auto`: try direct access first, then retry with Apify datacenter proxy if no rows are captured.
- `datacenter`: route through Apify datacenter proxy.
- `residential`: route through Apify residential proxy, optionally with `proxyCountryCode`.
- `proxyUrl`: use a full HTTP, HTTPS, or SOCKS proxy URL from Apify Residential, Bright Data, Oxylabs, or another managed provider.

### Example Input

```json
{
  "searchQuery": "running shoes",
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "maxResults": 100,
  "maxConcurrency": 1,
  "requestHandlerTimeoutSecs": 900,
  "proxyMode": "auto"
}
```

### Example Output

```json
{
  "resultType": "meta_ad",
  "libraryId": "123456789012345",
  "pageName": "Example Brand",
  "adStatus": "active",
  "startedRunning": "Jun 2026",
  "platforms": ["Facebook", "Instagram"],
  "cta": "Shop now",
  "creativeFormat": "image",
  "adText": "Visible ad copy from the public Meta Ads Library",
  "adUrl": "https://www.facebook.com/ads/library/?id=123456789012345",
  "dataQualityScore": 92,
  "scrapedAt": "2026-06-24T12:00:00.000Z"
}
```

### Pricing

`$10.00 / 1,000 delivered ads`

Billing is based on delivered ad rows written to the default dataset. Blocked pages, empty searches, login/captcha pages, timeouts, and no-data sources are stored as notices outside the paid dataset.

`maxResults` is a cap, not a promise that Meta will expose that many ads. If Meta exposes 37 useful ads from a 100-ad request, the dataset contains 37 delivered rows.

### Reliability

- Browser cleanup after errors.
- Whole-run and per-source timeout guards.
- Duplicate ad IDs removed before output.
- No paid error rows.
- Change snapshots stored outside the customer dataset.
- Graceful zero-row handling when Meta blocks or exposes no public ads.

# Actor input Schema

## `targetUrl` (type: `string`):

Full Meta Ads Library URL. When provided, this exact URL is used and the keyword, page, ad, and filter fields are ignored.

## `searchQuery` (type: `string`):

Keyword, brand, competitor, product, or offer to search in the public Meta Ads Library.

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

Optional extra keywords or brand names. Use this to collect more ad rows in one run.

## `pageId` (type: `string`):

Optional Facebook Page ID for advertiser/page-level ad discovery.

## `adId` (type: `string`):

Optional Meta Ad Library ID for checking one specific ad.

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

Optional full Meta Ads Library URLs. Use this for multiple advanced searches copied from the Ads Library UI.

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

Two-letter country code for keyword, page, and ad searches.

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

Choose active ads, inactive ads, or all ads.

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

Meta Ads Library ad category filter.

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

Filter ads by media type where Meta exposes the filter publicly.

## `isTargetedCountry` (type: `boolean`):

Limit results to ads Meta identifies as targeted to the selected country.

## `contentLanguages` (type: `array`):

Optional language codes such as en, es, de, fr, or ar.

## `sortMode` (type: `string`):

Preferred Meta Ads Library sort mode for URL-based searches.

## `sortDirection` (type: `string`):

Sort direction for supported Meta Ads Library views.

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

Maximum useful ad rows to write to the dataset. Billing is based on delivered rows, not requested rows.

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

Number of Ad Library sources to process in parallel. Keep at 1 for safest runs; increase for many keywords or URLs.

## `requestHandlerTimeoutSecs` (type: `integer`):

Maximum seconds spent on each query, page, ad, or target URL.

## `monitorChanges` (type: `boolean`):

Save snapshots and compare ad IDs, status, text, and start date across scheduled runs.

## `onlyChanges` (type: `boolean`):

When change detection is enabled, output only new or updated ad rows.

## `proxyUrl` (type: `string`):

Optional full HTTP, HTTPS, or SOCKS proxy URL. For serious Meta Ads Library scraping, use a reliable residential or managed proxy to improve capture rate when Meta blocks direct browser sessions.

## `proxyMode` (type: `string`):

Fallback Apify proxy mode used only when Custom proxy URL is empty.

## `proxyCountryCode` (type: `string`):

Optional two-letter country code for Apify residential proxy mode.

## `includeRawText` (type: `boolean`):

Include the raw text block used for parsing each ad row.

## `maxRunMinutes` (type: `integer`):

Whole-run cost guard. The Actor stops cleanly instead of waiting forever when Meta stalls or blocks loading.

## Actor input object example

```json
{
  "targetUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered",
  "searchQuery": "running shoes",
  "searchQueries": [
    "adidas",
    "puma",
    "reebok"
  ],
  "pageId": "",
  "adId": "",
  "adLibraryUrls": [
    "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shopify&search_type=keyword_unordered"
  ],
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "isTargetedCountry": false,
  "contentLanguages": [],
  "sortMode": "total_impressions",
  "sortDirection": "desc",
  "maxResults": 100,
  "maxConcurrency": 1,
  "requestHandlerTimeoutSecs": 900,
  "monitorChanges": false,
  "onlyChanges": false,
  "proxyUrl": "http://groups-RESIDENTIAL:YOUR_APIFY_TOKEN@proxy.apify.com:8000",
  "proxyMode": "none",
  "proxyCountryCode": "",
  "includeRawText": false,
  "maxRunMinutes": 12
}
```

# Actor output Schema

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

Normal runs contain delivered ad rows. When Output only changes is enabled, rows contain new or updated ad events.

# 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("seeb/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 = {}

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

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/NkwumOzSIr6zCV1B7/builds/8KVi6NbHsMgwgrmuZ/openapi.json