# Facebook Ads Library Scraper & Ad Intelligence (`fetch_cat/facebook-ads-library-scraper`) Actor

Export public Meta/Facebook ads by keyword, advertiser, or Ads Library URL. Filter by country, status, date, platform, language, and media; capture creative URLs, CTA, landing pages, page metadata, and public transparency ranges.

- **URL**: https://apify.com/fetch\_cat/facebook-ads-library-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Social media, Marketing, Developer tools
- **Stats:** 3 total users, 3 monthly users, 95.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.28 / 1,000 item extracteds

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

## Facebook Ads Library Scraper

Export public Meta and Facebook ads without building your own browser automation. Search by keyword, advertiser/page, or a full Ads Library URL; filter by country, status, date, placement, language, and media; and save structured creative intelligence for monitoring, research, and reporting.

Use it to collect public ad copy, advertiser names, library IDs, status, delivery dates, platforms, creative media URLs when exposed, landing links, and snapshot links from Facebook Ads Library.

### What does Facebook Ads Library Scraper do?

Facebook Ads Library Scraper helps you turn public ad search pages into a clean dataset.

- 🔎 Search public ads by keyword such as a brand, product, category, or campaign topic.
- 🔗 Paste full Ads Library URLs to preserve filters created in Meta's interface.
- 🏢 Search advertiser/page ads when you have a Facebook Page ID or supported page URL.
- 🌍 Filter by country code such as `US`, `GB`, `DE`, or `FR`.
- ✅ Choose active, inactive, or all public ads.
- 🎯 Choose exact-phrase or unordered keyword matching, Meta placements, and ad languages.
- 🖼️ Capture complete image/video arrays and a URL-only downloadable-media manifest, including dynamic creative variants exposed by Meta.
- 📊 Extract CTA, page/about metadata, and public spend, reach, impressions, and currency ranges when visible.
- 🔗 Optionally enrich public landing pages with redirects, metadata, product/price, and ecommerce indicators.
- 🧱 Enforce date and global item caps before item billing; null, blocked, handled-error, and unverifiable out-of-range rows are never emitted as paid items.
- 📦 Export results as JSON, CSV, Excel, XML, RSS, or through the Apify API.

### Who is it for?

This actor is useful for teams that need public ad intelligence at repeatable intervals.

- 📣 Marketing teams tracking competitor messaging.
- 🧪 Growth teams testing positioning across markets.
- 🧾 Agencies preparing client competitor reports.
- 🛡️ Brand monitors watching impersonation or risky ad claims.
- 🎓 Researchers studying public advertising trends.
- 🧰 Data teams feeding ad examples into dashboards and AI workflows.

### Why use it?

The Meta Ads Library website is built for browsing. It is not convenient when you need a repeatable table of public ads. This actor packages the workflow into an Apify actor so you can schedule it, call it from an API, and combine the output with the rest of your data stack.

### What data can you extract?

| Field | Description |
| --- | --- |
| `query` | Keyword used for the run, when keyword mode is used. |
| `runTag` | Optional user label copied to every row for downstream routing. |
| `country` | Country filter used for the search. |
| `advertiserName` | Advertiser or page name visible on the ad card. |
| `advertiserPageUrl` | Public advertiser page URL when exposed. |
| `advertiserPageId` / `pageMetadata` | Public page ID plus visible name, URL, profile image, category, follower/like, and disclaimer metadata. |
| `libraryId` | Meta Ads Library ID for the public ad. |
| `creativeVariantId` | Deterministic dedupe key for one library ID + creative variant. |
| `adStatus` | Active or inactive status when visible. |
| `startedAt` | Start date text when visible. |
| `endedAt` | End date text when visible. |
| `platforms` | Meta platforms detected in the card text. |
| `adText` | Main visible ad copy. |
| `caption` | Optional caption field. |
| `adTitle` / `callToAction` | Visible headline and CTA when detected. |
| `creativeType` | Image, video, mixed, or unknown. |
| `imageUrls` / `videoUrls` | Deduplicated creative asset arrays. |
| `creativeVariants` / `mediaManifest` | Variant-aware asset groups plus downloadable URLs, type, extension, and optional reachability status. No media binary is stored by default. |
| `spend` / `reach` / `impressions` / `currency` | Public transparency ranges when Meta exposes them. |
| `landingUrl` / `landingPage` | Destination URL and optional landing-page/ecommerce enrichment. |
| `diagnostics` | Per-item partial/missing-field and date-verification details. Run-level source, retry, block, deadline, cap, and rejection counts are saved in `RUN_SUMMARY` and the backward-compatible `OUTPUT` record. |
| `snapshotUrl` | Meta Ads Library snapshot URL. |
| `sourceUrl` | Ads Library search URL used for extraction. |
| `scrapedAt` | ISO timestamp when the item was scraped. |

### Pricing

This Actor uses pay-per-event pricing. A `start` event is charged after valid input is confirmed, then an `item` event is charged only for each valid ad record saved to the dataset. See the [live Pricing tab](https://apify.com/fetch_cat/facebook-ads-library-scraper/pricing) for current rates. Apify may separately charge for platform compute, storage, proxy traffic, or data transfer. Start with the default `maxItems: 10`, verify the dataset, and then scale.

### Quick start

1. Open the actor on Apify.
2. Enter a keyword such as `coffee` or a known advertiser page ID.
3. Choose a country such as `US`.
4. Keep `maxItems` low for the first run.
5. Start the actor.
6. Download the dataset or call it through the API.

### Input settings

| Input label | JSON key | Description |
| --- | --- | --- |
| Keyword query | `query` | Search term; separate multiple terms with commas or new lines. |
| Ads Library URLs | `startUrls` | Full public Ads Library URLs; takes precedence over query/page inputs. |
| Advertiser page URL | `advertiserPageUrl` | Public Facebook advertiser Page URL. |
| Advertiser page ID | `pageId` | Numeric Facebook Page ID for advertiser mode. |
| Keyword matching | `searchType` | Words in any order or exact phrase. |
| Country | `country` | Two-letter Ads Library country code. |
| Ad status | `activeStatus` | Active, inactive, or all ads. |
| Ad type | `adType` | All ads or political and issue ads. |
| Media type | `mediaType` | Filter by image, video, meme, or no media. |
| Platforms | `platforms` | Optional Facebook, Instagram, Messenger, Audience Network, Threads, or WhatsApp placements. |
| Languages | `languages` | Optional Meta ad-language codes. |
| Start date | `startDate` | Optional delivery-date lower bound (`YYYY-MM-DD`). |
| End date | `endDate` | Optional delivery-date upper bound (`YYYY-MM-DD`). |
| Maximum ads | `maxItems` | Hard global cap on valid, billed creative variants. |
| Enrich landing pages | `enrichLandingPages` | Add public landing-page and ecommerce metadata. |
| Validate creative media URLs | `validateMediaUrls` | Check media-manifest URL reachability. |
| Safe run deadline | `maxRunSeconds` | Stop opening sources early enough to preserve saved results. |
| Run tag | `runTag` | Optional label copied to each row for spreadsheets and pipelines. |
| Proxy configuration | `proxyConfiguration` | Optional Apify Proxy settings. |

#### Keyword query

Use `query` to search public ads by text. Enter one keyword, or separate multiple keywords with commas/new lines when you want one combined export. Examples:

- `nike`
- `coffee`
- `running shoes`
- `meal delivery`
- `coffee, nike, travel`

#### Advertiser page URL or page ID

Use `pageId` when you know the numeric Facebook Page ID. Some page URLs also contain an ID and can be passed as `advertiserPageUrl`.

#### Full Ads Library URLs

Use `startUrls` when you already configured a search in Meta Ads Library. This is also the most flexible way to carry filters Meta adds to its public URL. Only `facebook.com/ads/library/` URLs are accepted.

#### Country

Use a two-letter Ads Library country code. The default is `US`.

#### Ad status

Set `activeStatus` to one of:

- `active`
- `inactive`
- `all`

#### Ad type

The `adType` default is `all`. Political and issue ads are available through the dedicated option where supported by Meta.

#### Media type

Set `mediaType` to choose all media, image, video, memes, image and meme, or no-media results.

#### Date range

Use optional `startDate` and `endDate` in `YYYY-MM-DD` format when you need a delivery date window.

#### Maximum ads

`maxItems` is a hard global cap across all queries. It is applied after date validation and creative-variant dedupe but before dataset write/item billing.

#### Optional landing-page and media validation

Set `enrichLandingPages: true` to fetch public destinations and add final URL, HTTP status, title, description, canonical URL, ecommerce detection, product name, price, and currency. Set `validateMediaUrls: true` to make lightweight HEAD requests and annotate each media-manifest URL with reachability/status. Both are off by default to minimize requests.

#### Proxy configuration

Leave `proxyConfiguration` empty for direct access. If Meta shows verification or empty pages for your run, enable Apify Proxy and choose the lowest-cost proxy group that works for your target country.

### Ready-to-run examples

Use these public Store examples as starting points:

- [Active US coffee ads](https://apify.com/fetch_cat/facebook-ads-library-scraper/examples/active-us-coffee-facebook-ads)
- [Advertiser page monitor](https://apify.com/fetch_cat/facebook-ads-library-scraper/examples/advertiser-page-facebook-ads-monitor)
- [Meal-delivery competitive research](https://apify.com/fetch_cat/facebook-ads-library-scraper/examples/meal-delivery-facebook-ads-competitive-research)
- [Public issue ads research](https://apify.com/fetch_cat/facebook-ads-library-scraper/examples/public-issue-ads-library-research)
- [Running-shoes video ads](https://apify.com/fetch_cat/facebook-ads-library-scraper/examples/running-shoes-video-facebook-ads)

### Example input

```json
{
  "query": "coffee",
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "maxItems": 10,
  "enrichLandingPages": false,
  "validateMediaUrls": false
}
```

### Example output

```json
{
  "query": "coffee",
  "country": "US",
  "advertiserName": "Example Coffee",
  "advertiserPageUrl": "https://www.facebook.com/example",
  "libraryId": "1234567890",
  "creativeVariantId": "variant_6df4d9a1",
  "pageMetadata": { "pageId": "987654321", "name": "Example Coffee" },
  "adStatus": "Active",
  "startedAt": "Jan 1, 2026",
  "endedAt": null,
  "platforms": ["Facebook", "Instagram"],
  "adText": "Try our new roast today.",
  "caption": null,
  "adTitle": "New roast",
  "callToAction": "Shop now",
  "creativeType": "image",
  "imageUrls": ["https://cdn.example/creative.jpg"],
  "videoUrls": [],
  "creativeVariants": [{ "variantId": "variant_6df4d9a1", "imageUrls": ["https://cdn.example/creative.jpg"], "videoUrls": [] }],
  "mediaManifest": [{ "url": "https://cdn.example/creative.jpg", "type": "image", "fileExtension": "jpg", "reachable": null }],
  "spend": { "lower": 100, "upper": 199, "text": "$100-$199" },
  "reach": { "lower": 1000, "upper": 5000, "text": "1K-5K" },
  "impressions": null,
  "currency": "USD",
  "landingUrl": "https://example.com",
  "landingPage": null,
  "diagnostics": { "partial": false, "missingFields": [], "dateVerified": false },
  "snapshotUrl": "https://www.facebook.com/ads/library/?id=1234567890",
  "sourceUrl": "https://www.facebook.com/ads/library/...",
  "scrapedAt": "2026-07-03T00:00:00.000Z"
}
```

### Tips for better results

- Use specific brand or product terms instead of very broad terms.
- Match the country to the market you are researching.
- Use `active` for current competitive monitoring.
- Use `all` when building historical examples.
- Increase `maxItems` only after a small run succeeds.
- Keep separate runs for different brands so exports stay easy to compare.

### Scheduling

You can schedule the actor in Apify to run daily, weekly, or monthly. Common schedules include:

- Daily brand monitoring.
- Weekly competitor ad review.
- Monthly creative swipe-file export.
- Campaign launch monitoring during a specific date range.

### Integrations

Use the dataset output with:

- Google Sheets exports for quick reporting.
- BI dashboards for competitor trend tracking.
- Slack or email alerts through Apify integrations.
- Webhooks that trigger when a run finishes.
- Data warehouses through Apify API calls.
- AI analysis pipelines that summarize ad themes.

### API usage

#### Node.js

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/facebook-ads-library-scraper').call({
  query: 'coffee',
  country: 'US',
  activeStatus: 'active',
  maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('fetch_cat/facebook-ads-library-scraper').call(run_input={
    'query': 'coffee',
    'country': 'US',
    'activeStatus': 'active',
    'maxItems': 10,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~facebook-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"query":"coffee","country":"US","activeStatus":"active","maxItems":10}'
```

### MCP usage

Use Apify MCP with Claude Desktop or Claude Code to run the actor from natural language prompts.

MCP URL:

```text
https://mcp.apify.com?tools=fetch_cat/facebook-ads-library-scraper
```

Claude Code setup:

```bash
claude mcp add --transport http apify-facebook-ads-library https://mcp.apify.com?tools=fetch_cat/facebook-ads-library-scraper
```

Claude Desktop JSON config:

```json
{
  "mcpServers": {
    "apify-facebook-ads-library": {
      "url": "https://mcp.apify.com?tools=fetch_cat/facebook-ads-library-scraper"
    }
  }
}
```

Example prompts:

- "Run Facebook Ads Library Scraper for coffee ads in the US and summarize the top messages."
- "Collect 20 active ads for this advertiser page ID and group the copy themes."
- "Compare Facebook and Instagram platform mentions in the latest dataset."

### Troubleshooting

#### The run returns no ads

The query may have no public ads in the selected country/status combination. Try a broader keyword, a different country, or `activeStatus: all`.

#### Meta shows verification

Try Apify Proxy, lower `maxItems`, or run again later. Verification pages can happen on public sites with automated traffic.

#### Advertiser page URL does not work

Use a numeric `pageId` if the URL does not contain one. Vanity page URLs do not always expose a numeric ID.

### Limits

- This actor does not log in to Facebook.
- Some fields are only saved when visible in the public card.
- Creative URLs may expire or vary by region.
- Very broad searches may require multiple runs split by country or date range.
- The default 2 GB memory allocation provides headroom for Meta's browser-heavy public interface; lowering task memory can make broad searches less reliable.

### Privacy and data handling

This Actor uses your URLs, search terms, identifiers, filters, and limits only to fetch the requested public Ads Library data and write results to your Apify dataset and key-value store. It does not accept Facebook passwords or store login credentials.

Data may pass through Apify platform services and Apify Proxy during a run. FetchCat does not send inputs or outputs to advertising networks, data brokers, or model-training services, and does not retain run data outside Apify storage unless you explicitly share a run for transient support debugging.

You are responsible for using the Actor lawfully, respecting applicable terms, and reviewing public output before storing, sharing, or combining it with other data.

### Related scrapers

#### More Facebook scrapers

- [Facebook Reviews Scraper](https://apify.com/fetch_cat/facebook-reviews-scraper)
- [Facebook Marketplace Scraper](https://apify.com/fetch_cat/facebook-marketplace-scraper)
- [Facebook Events Scraper](https://apify.com/fetch_cat/facebook-events-scraper)
- [Facebook Comments Scraper](https://apify.com/fetch_cat/facebook-comments-scraper)
- [Facebook Reels Scraper](https://apify.com/fetch_cat/facebook-reels-scraper)

Explore related actors from the same catalog:

- [Instagram Stories & Highlights Scraper](https://apify.com/fetch_cat/instagram-stories-highlights-scraper)
- [Instagram Profile Posts Scraper](https://apify.com/fetch_cat/instagram-profile-posts-scraper)
- [LinkedIn Jobs Scraper](https://apify.com/fetch_cat/linkedin-jobs-scraper)

### Support

If you need a field that appears in the Ads Library page but is missing from the dataset, open an issue and include:

- The Apify run ID or run URL.
- The exact input JSON, with secrets removed.
- The expected output.
- The actual output the dataset returned.
- A reproducible public URL, such as the public ad snapshot or Ads Library search URL.

### FAQ

#### Can I scrape inactive ads?

Yes. Set `activeStatus` to `inactive` or `all`.

#### Can I use it without a Facebook account?

Yes. The actor is designed for public Ads Library pages and does not accept credentials.

#### Can I run it every day?

Yes. Use Apify schedules and keep inputs focused for predictable costs.

#### Does it include Instagram ads?

When Meta exposes platform labels on the ad card, the `platforms` field can include Instagram.

#### Can I export to CSV?

Yes. Apify datasets can be downloaded as CSV, JSON, Excel, XML, RSS, and HTML.

# Actor input Schema

## `query` (type: `string`):

Keyword to search in public Ads Library, for example a brand, product, or topic. Separate multiple keywords with commas or new lines for one combined export.

## `startUrls` (type: `array`):

Optional full public Facebook Ads Library search URLs. Use these to preserve filters copied from Ads Library. When supplied, they take precedence over query/page inputs.

## `advertiserPageUrl` (type: `string`):

Optional Facebook Page URL for advertiser/page mode. Use either a keyword query or a page URL/page ID.

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

Optional Facebook Page ID for advertiser/page mode.

## `searchType` (type: `string`):

Match words in any order, or require the exact phrase.

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

Two-letter Meta Ads Library country code.

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

Filter by active, inactive, or all ads.

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

Meta Ads Library ad type filter.

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

Creative media filter.

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

Optional Meta placement filters.

## `languages` (type: `array`):

Optional ad-language codes such as en, de, or pt\_PT.

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

Optional lower bound for ad delivery start date in YYYY-MM-DD format.

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

Optional upper bound for ad delivery date in YYYY-MM-DD format.

## `maxItems` (type: `integer`):

Hard maximum number of valid creative-variant records to save and bill across all queries.

## `enrichLandingPages` (type: `boolean`):

Fetch each public destination page and add redirect, title, description, canonical, product, price, currency, and ecommerce indicators. Disabled by default to minimize requests.

## `validateMediaUrls` (type: `boolean`):

Send lightweight HEAD requests to manifest URLs and record reachability/status. Disabled by default because CDN validation adds requests.

## `maxRunSeconds` (type: `integer`):

Stop opening new sources before the platform timeout and preserve already saved results.

## `runTag` (type: `string`):

Optional label copied to every output row, useful for routing saved tasks into spreadsheets, Clay, or data warehouses.

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

Optional proxy settings. Leave empty for direct access; enable Apify Proxy if Meta shows verification or empty pages.

## Actor input object example

```json
{
  "query": "nike, coffee, shoes",
  "startUrls": [],
  "searchType": "keyword_unordered",
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "maxItems": 10,
  "enrichLandingPages": false,
  "validateMediaUrls": false,
  "maxRunSeconds": 540
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `runSummary` (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 = {
    "query": "nike, coffee, shoes",
    "startUrls": [],
    "country": "US",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/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 = {
    "query": "nike, coffee, shoes",
    "startUrls": [],
    "country": "US",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/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 '{
  "query": "nike, coffee, shoes",
  "startUrls": [],
  "country": "US",
  "maxItems": 10
}' |
apify call fetch_cat/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/0xeVLpUizP1FnAjJh/builds/0HShOhu1uQYVEBtCy/openapi.json