# Meta | Facebook Ads Library Scraper + Ad Details (`sophisticated_zythum/meta-ads-library-scraper`) Actor

Collect public ads, advertiser information, creatives, and changes from Meta (Facebook) Ads Library.

- **URL**: https://apify.com/sophisticated\_zythum/meta-ads-library-scraper.md
- **Developed by:** [Md Saif Ahmed](https://apify.com/sophisticated_zythum) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 ad results

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

## Meta | Facebook Ads Library Scraper

Collect public ads from the Meta Ads Library without login cookies. Search by keyword or advertiser Page ID, or paste an existing Ads Library URL. The Actor returns one structured record per ad with its creative, advertiser, delivery status, platforms, landing page, and media.

Use the optional **Open ad details** enrichment when you also need the transparency and audience fields that Meta makes available for a particular ad and country.

### What can you use it for?

- Research competitors and the ads they are currently running
- Find advertising angles, copy, calls to action, images, and videos
- Compare advertisers, landing pages, and offers across countries
- Build a searchable archive of ads from selected brands or keywords
- Monitor when ads appear, change, or stop running
- Export ad data to CSV, Excel, JSON, XML, or your own integration

### What data does it collect?

Standard mode is optimized for speed and collects data visible on each Ads Library result card:

- Meta Library ID and source URL
- Advertiser name, Page ID, and Page URL
- Active or inactive status and start/end dates
- Publisher platforms shown by Meta
- Primary ad text, headline, description, and call to action
- Destination and display URLs
- Image and video URLs, creative variants, and structured media records
- Disclaimer, funding entity, and public delivery metrics when present
- First-seen, last-seen, and change-tracking metadata

When **Open ad details** is enabled, the Actor opens each ad's details panel and also attempts to collect:

- Transparency by location
- Targeted location, age, and gender information
- Advertiser information
- Advertiser, payer, and beneficiary information
- Spend, impressions, reach, and delivery data

Meta only publishes some transparency fields for certain ad categories and countries. A field may therefore be empty even when detail enrichment completed successfully.

### Quick start

1. Open the Actor's **Input** tab.
2. Choose one input method: paste an Ads Library URL, add search terms, or add advertiser Page IDs.
3. Set the maximum number of ads and any filters you need.
4. Leave **Open ad details** off for a faster standard run, or enable it for additional public transparency data.
5. Click **Start**.
6. Open the **Dataset** to preview, filter, download, or access the results through the Apify API.

No Facebook account or cookies are required.

### Choose an input method

#### 1. Paste an Ads Library URL

Use this when you have already configured a search on Facebook. Copy the full URL from the Ads Library and add it to **Ads Library URLs**.

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=running%20shoes&search_type=keyword_unordered"
    }
  ],
  "maxAds": 100
}
```

The Actor preserves the filters contained in a pasted URL. The separate country, status, category, media, platform, and date fields are used to build searches from keywords or Page IDs; they do not replace parameters in a pasted URL.

#### 2. Search by keyword

Enter one or more search terms. The Actor creates a search for every term and selected country.

```json
{
  "searchQueries": ["running shoes", "sportswear"],
  "countries": ["US", "GB"],
  "activeStatus": "active",
  "mediaType": "video",
  "maxAds": 100
}
```

#### 3. Search by advertiser Page ID

Use Page IDs to collect ads from specific advertisers.

```json
{
  "pageIds": ["123456789012345"],
  "countries": ["US"],
  "activeStatus": "all",
  "maxAds": 100
}
```

You can provide multiple URLs, keywords, or Page IDs in one run. Duplicate Library IDs are saved only once.

### Input options

| Option | What it does |
| --- | --- |
| **Ads Library URLs** | Uses complete search or advertiser URLs copied from Meta Ads Library. |
| **Search terms** | Builds a search for each keyword and country. |
| **Advertiser Page IDs** | Collects ads associated with selected Meta Pages. |
| **Countries** | Sets two-letter country codes for generated keyword and Page ID searches. |
| **Ad status** | Selects all, active, or inactive ads. |
| **Ad category** | Selects all ads, political/issue, housing, employment, or credit ads. |
| **Media type** | Selects all media, images, videos, memes, or ads without image/video. |
| **Platforms** | Filters generated searches by Meta publisher platform. |
| **Started after/before** | Limits generated searches by the ad start date. |
| **Maximum ads** | Sets the maximum number of unique records saved in the run. |
| **Open ad details** | Opens every ad's detail panel for additional paid enrichment. |
| **Download creative media** | Stores public image and video files in the run's key-value store. |
| **Save only new or changed ads** | Omits records that have not changed since a previous run. |
| **Monitoring key** | Identifies the persistent watchlist shared by scheduled runs. |
| **Maximum concurrency** | Controls how many browser pages are processed at once. |
| **Proxy configuration** | Enables Apify residential or external proxies for greater reliability. |

### Standard collection or detail enrichment?

| | Standard collection | Open ad details |
| --- | --- | --- |
| Default | Yes | No |
| Result-card data and creatives | Yes | Yes |
| Landing page, CTA, images, and videos | Yes | Yes |
| Opens every details panel | No | Yes |
| Location, age, gender, advertiser/payer transparency | No | When Meta publishes it |
| Speed | Faster | Slower |
| Price per saved ad | $0.008 | $0.020 total |

Detail enrichment adds **$0.012 per saved ad** to the standard result price. It is charged when the Actor processes the detail panel, including cases where Meta does not publish optional country-restricted fields.

#### Price examples

| Saved ads | Standard | With ad details |
| ---: | ---: | ---: |
| 100 | $0.80 | $2.00 |
| 1,000 | $8.00 | $20.00 |

Your Apify run may also incur normal platform compute and proxy usage. The Actor respects the maximum charge set for the run and stops before starting a result that the remaining budget cannot cover.

### Output example

Every Dataset item represents one unique Meta Library ad. Empty values mean Meta did not display that information for the ad.

```json
{
  "adArchiveId": "123456789012345",
  "advertiserName": "Example Brand",
  "advertiserPageId": "987654321098765",
  "advertiserPageUrl": "https://www.facebook.com/example",
  "activeStatus": "active",
  "startedAt": "2026-09-01",
  "endedAt": "",
  "platforms": ["facebook", "instagram"],
  "body": "Discover our new collection.",
  "headline": "Shop the latest styles",
  "description": "Free delivery this week",
  "cta": "Shop Now",
  "destinationUrl": "https://example.com/collection",
  "displayUrl": "EXAMPLE.COM",
  "imageUrls": ["https://.../creative.jpg"],
  "videoUrls": [],
  "variantCount": 1,
  "transparencyByLocation": {},
  "aboutAdvertiser": "Example Brand creates performance footwear.",
  "advertiserAndPayer": {},
  "firstSeenAt": "2026-09-16T10:00:00.000Z",
  "lastSeenAt": "2026-09-16T10:00:00.000Z",
  "changeType": "new",
  "detailEnrichmentIncluded": false,
  "sourceUrl": "https://www.facebook.com/ads/library/?id=123456789012345"
}
```

The `media` array provides structured creative records for integrations, while the flat image and video fields are convenient for CSV and Excel exports. If media download is enabled, the downloaded files are stored separately in the run's key-value store.

### Monitor new and changed ads

Use this workflow to track an advertiser or search over time:

1. Choose a stable **Monitoring key**, such as `competitor-nike-us`.
2. Enable **Save only new or changed ads**.
3. Save the Actor input as an Apify task.
4. Schedule the task to run daily or at your preferred interval.

Runs with the same monitoring key share saved state. The first run returns all matched ads. Later runs return ads that are new or whose status, copy, destination, dates, creative URLs, or variant count changed. `firstSeenAt`, `lastSeenAt`, and `changeType` make the changes easy to track.

Use a different monitoring key for each independent advertiser, country, or watchlist.

### Do I need a proxy?

No proxy is required for small tests, and the default example can run without one. For larger runs, repeated schedules, or more consistent coverage, enable an Apify residential proxy and choose a country that matches the search market.

Proxy rotation improves access reliability but does not guarantee that Meta will return every possible result. Coverage can vary with country, query, current Meta behavior, and public availability.

### Frequently asked questions

#### Why are headline or CTA fields sometimes empty?

Some ad formats do not display a separate headline, description, or CTA. The Actor keeps those fields empty rather than copying unrelated text into them.

#### Why are age, gender, location, spend, or reach empty?

Meta restricts these fields by country and ad category. Enable **Open ad details** to attempt collection; values remain empty when the details panel does not publish them.

#### Why are several ads visually identical?

Meta can assign separate Library IDs to different deliveries or variants of the same creative. Each unique Library ID is a separate Dataset record.

#### Does the maximum ads value guarantee that many results?

It is an upper limit. A run can return fewer records if Meta exposes fewer matching ads, blocks additional loading, or the run reaches its time or charge limit.

#### Can the Actor download images and videos?

Yes. Enable **Download creative media** to save accessible public files in the key-value store. Media URLs are included in Dataset records even when downloads are disabled.

### Limitations

- The Actor collects only information publicly displayed by Meta Ads Library.
- Detail fields vary by country, ad type, and Meta's disclosure rules.
- Meta can change its interface, limit results, or temporarily challenge automated access.
- Deleted ads and expired media URLs may no longer be accessible.
- Results represent the data Meta returned during the run and are not a guarantee of complete platform coverage.

Use the Actor responsibly and follow applicable laws, Meta's terms, and Apify's platform policies.

# Actor input Schema

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

Search result or advertiser URLs copied from Meta Ads Library.

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

Create an Ads Library search for every term and country.

## `pageIds` (type: `array`):

Meta Page IDs whose ads should be collected.

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

Two-letter country codes used in generated Ads Library URLs.

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

Collect all ads, active ads, or inactive ads.

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

Filter the Ads Library by its supported ad category.

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

Limit results to a specific creative format.

## `publisherPlatforms` (type: `array`):

Optional Meta platforms, such as facebook, instagram, messenger, and audience\_network.

## `dateMin` (type: `string`):

Optional date in YYYY-MM-DD format.

## `dateMax` (type: `string`):

Optional date in YYYY-MM-DD format.

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

Maximum unique ads saved across the run.

## `includeDetails` (type: `boolean`):

Optional paid enrichment. Adds $0.012 per saved ad and opens each ad's details modal to collect public transparency fields, including location, age, gender, advertiser, payer, spend, impressions, and reach when Meta provides them. Leave off for the fastest $0.008-per-ad collection.

## `downloadMedia` (type: `boolean`):

Save public image and video files to the run's key-value store.

## `onlyNewOrChanged` (type: `boolean`):

Compare ads with a persistent monitoring state and omit unchanged records.

## `monitoringKey` (type: `string`):

Reuse the same key on scheduled runs to track changes for one watchlist.

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

Maximum number of browser pages processed at the same time.

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

The scraper can run without a proxy. Use a residential proxy for fuller and more reliable production results.

## Actor input object example

```json
{
  "countries": [
    "US"
  ],
  "activeStatus": "all",
  "adType": "all",
  "mediaType": "all",
  "maxAds": 100,
  "includeDetails": false,
  "downloadMedia": false,
  "onlyNewOrChanged": false,
  "maxConcurrency": 1,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Normalized ads collected during this run.

## `progress` (type: `string`):

Latest processing counters for the run.

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

Final processed and saved counts.

## `media` (type: `string`):

Creative files downloaded when downloadMedia is enabled.

# 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("sophisticated_zythum/meta-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("sophisticated_zythum/meta-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 '{}' |
apify call sophisticated_zythum/meta-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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