# Facebook Ad Library Scraper: Winning Ads, Meta, EU Reach (`himanshu-data/meta-ad-library-scraper`) Actor

Facebook Ad Library scraper for Meta ads by keyword, page or Ad Library link. Ad text, creatives, landing page, days running, winning-ad filters and EU reach. No login.

- **URL**: https://apify.com/himanshu-data/meta-ad-library-scraper.md
- **Developed by:** [Himanshu Agrawal](https://apify.com/himanshu-data) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 ads

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Facebook Ad Library Scraper (Meta Ads, Winning Ads, EU Reach)

This Facebook Ad Library scraper pulls ads from the **Meta Ad Library** (Facebook, Instagram, Messenger, Threads and Audience Network) by **keyword**, **advertiser** or any **Ad Library link**. Every ad comes with its text, headline, landing page, call to action, images, videos and carousel cards, plus the **start date, days running**, platforms, **how many ads use the same creative** and the advertiser's page. Keep only **winning ads**, and add **EU reach by country, age and gender** and who paid for the ad, with no login, no Facebook account and no API token.

### What you can use it for

- **Competitor ad research:** scrape every running Facebook and Instagram ad of a competitor, with its offers, hooks and landing pages.
- **Find winning ads for e-commerce and dropshipping:** keep ads that have run for 30+ days, or creatives used in many ads.
- **Creative inspiration and swipe files:** headlines, ad copy, calls to action and videos for any niche.
- **Agency prospecting:** find brands that advertise on Meta, with their page, likes and Instagram.
- **EU and political ads research:** reach by age and gender for ads shown in the EU, spend and impressions for political ads, and who paid.

### How to use

1. Open the [Facebook Ad Library Scraper](https://apify.com/himanshu-data/meta-ad-library-scraper) page and click **Try for free** (you sign in to your Apify account).
2. Enter search keywords, advertiser pages, or links copied from facebook.com/ads/library.
3. Pick a country and, if you want, set **Min days running** or **Min ads using the same creative**.
4. Click **Start**. Ads appear in the **Output** tab with thumbnails.
5. Export as JSON, CSV or Excel.

**API:** `POST https://api.apify.com/v2/acts/himanshu-data~meta-ad-library-scraper/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>` with the input as JSON in the body returns the ads in one call.

### Input

| Field | What it does |
|---|---|
| Search keywords | A product, niche, brand or competitor. One per line. |
| Match the exact phrase | Only ads with that exact phrase. |
| Advertisers (Facebook pages) | Page names (Nike), page links, page IDs or Ad Library page links. |
| Ad Library links | Links copied from facebook.com/ads/library: a search with your filters, an advertiser, or one ad. |
| Country, ad status, category, media type, platforms, languages, start dates, sort | The same filters as the Ad Library. |
| Max ads per keyword, advertiser or link | Meta returns about 10 ads per page. |
| Min days running, Min ads using the same creative | Winning-ad filters. Skipped ads are free. |
| Add ad details | EU reach, target audience, who paid and advertiser profile (extra event). |

```json
{
  "searchQueries": ["protein powder"],
  "pages": ["Nike"],
  "country": "US",
  "maxAdsPerSource": 200,
  "minDaysRunning": 30
}
```

### Output

One row per ad (real output, October 2026; shortened):

```json
{
  "adArchiveId": "1298488261783748",
  "pageName": "Whatnot",
  "adText": "Take your sneaker game to the next level with incredible deals on the hottest styles⚡Live on Whatnot",
  "headline": "Whatnot: Shop, Sell, Connect",
  "displayLink": "itunes.apple.com",
  "linkUrl": "http://itunes.apple.com/app/id1488269261",
  "ctaText": "Install now",
  "displayFormat": "VIDEO",
  "isActive": true,
  "startDate": "2026-05-13T07:00:00.000Z",
  "daysRunning": 160,
  "adsUsingThisCreative": 2,
  "platforms": ["facebook", "instagram", "messenger"],
  "videos": [{ "hdUrl": "https://video-phl2-1.xx.fbcdn.net/...", "previewImageUrl": "https://scontent-phl2-1.xx.fbcdn.net/..." }],
  "pageId": "112727500143177",
  "pageUrl": "https://facebook.com/RealWhatnot",
  "pageLikes": 302751,
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1298488261783748"
}
```

Rows also include image URLs, carousel cards, text variants, page picture and categories, countries, and spend, impressions and "paid for by" for political ads.

With **Add ad details**, an ad shown in Germany gets (real output, shortened):

```json
{
  "euTotalReach": 3846070,
  "targetLocations": [{ "name": "Germany", "type": "countries", "excluded": false }],
  "targetGender": "All",
  "targetAgeMin": 18,
  "targetAgeMax": 65,
  "euReachByCountryAgeGender": [{ "country": "DE", "ageRange": "25-34", "male": 758405, "female": 621360, "unknown": 41997 }],
  "payers": [{ "payer": "essencemediacom", "beneficiary": "adidas" }],
  "instagramFollowers": 29831342
}
```

### Pricing

**$0.50 per 1,000 ads** on paid Apify plans, less on Scale and Business. **Ad details** cost $0.50 per 1,000 ads more, only when turned on. Ads skipped by the winning-ad filters are free.

### Integrations

- **Apify API** to start runs and read the ads from any language.
- **Python and JavaScript clients** (`apify-client`) for scripts and dashboards.
- **Zapier, Make and n8n** to send new ads to Google Sheets, Airtable, Notion or Slack.
- **MCP for AI agents:** connect the Apify MCP server to Claude, ChatGPT or another MCP client and the agent can search the Ad Library through this Actor.
- **Schedules and webhooks** in Apify Console to track a competitor's ads every week.

### FAQ

**Do I need a Facebook account or a Meta API token?**
No. You only need an Apify account. The Actor reads the public Ad Library without login.

**How many ads can I get?**
Up to 50,000 ads per keyword, advertiser or link. Meta returns about 10 ads per page, so large runs take longer.

**Why did I get fewer ads than I asked for?**
The Ad Library may simply have fewer ads for that search, country or status (the default is active ads only). The winning-ad filters also skip ads, and skipped ads are free. Try all countries, ad status "Active and inactive", or a broader keyword.

**How do I find winning ads?**
Set **Min days running** (for example 30) to keep ads an advertiser keeps paying for, and **Min ads using the same creative** to keep creatives that were scaled into many ads.

**Can I scrape a filtered Ad Library search?**
Yes. Set filters on facebook.com/ads/library, copy the link and paste it into **Ad Library links**: every filter is kept.

**Can I schedule it?**
Yes. Create a schedule in Apify Console and connect Zapier, Make, n8n or a webhook to get the ads where you work.

**Which export formats are there?**
JSON, CSV, Excel, XML, HTML and JSONL from the dataset, or the API.

**Is it legal to scrape the Meta Ad Library?**
The Ad Library is a public transparency tool, and the Actor collects only that public data. Follow Meta's terms and the laws where you live, and take care with any personal data. This is not legal advice.

### Tips

- Days running counts from the start date to today for running ads, and to the end date for stopped ads.
- Catalog ads (format DPA) show placeholders such as `{{product.name}}` in the headline; the real products are in `cards`.
- Image and video links from Meta expire after a few days, so download what you want to keep.
- EU reach details exist only for ads shown in the EU.
- Meta rate-limits data-center proxies. If the proxy you pick keeps hitting the limit, the run switches to residential proxies by itself.
- Need Google ads too? Use our [Google Ads Transparency Scraper](https://apify.com/himanshu-data/google-ads-transparency-scraper).

# Actor input Schema

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

Words to search in the Ad Library, e.g. a product, niche, brand or competitor. One per line.

## `exactPhrase` (type: `boolean`):

On: "running shoes" finds only that phrase. Off: ads containing all the words in any order.

## `pages` (type: `array`):

Every ad of an advertiser. Page names (Nike), page links (https://www.facebook.com/nike), page IDs (15087023444) or Ad Library page links (view_all_page_id=...). One per line.

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

Links copied from facebook.com/ads/library with your filters set there: a search, an advertiser, or one ad (?id=...). Their own filters are used.

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

Ads shown in this country. EU countries also unlock reach details (see Ad details).

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

Running ads, stopped ads, or both.

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

Political and issue ads include spend, impressions and who paid for them.

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

Only ads with this kind of creative.

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

Only ads shown on these platforms. Leave empty for all.

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

Two-letter language codes, e.g. en, es, hi. Leave empty for all.

## `startedAfter` (type: `string`):

Only ads that started on or after this date.

## `startedBefore` (type: `string`):

Only ads that started on or before this date.

## `sortBy` (type: `string`):

Most impressions puts the biggest ads first.

## `maxAdsPerSource` (type: `integer`):

Meta returns about 10 ads per page.

## `minDaysRunning` (type: `integer`):

Only ads running for at least this many days. Advertisers keep paying for ads that work, so long runners are proven ads. Skipped ads are free.

## `minAdsUsingCreative` (type: `integer`):

Only ads whose creative runs in at least this many ads (scaled creatives). Skipped ads are free.

## `includeAdDetails` (type: `boolean`):

One extra lookup per ad: EU reach (total and by country, age and gender) and target audience for ads shown in the EU, who paid for the ad, and the advertiser's about text, verification and Instagram. Charged as a separate event.

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

Meta limits visitors per IP, so residential proxies are used by default. If another proxy keeps getting rate-limited, the run switches to residential by itself.

## Actor input object example

```json
{
  "searchQueries": [
    "nike"
  ],
  "exactPhrase": false,
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "sortBy": "relevance",
  "maxAdsPerSource": 20,
  "includeAdDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (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 = {
    "searchQueries": [
        "nike"
    ],
    "country": "US",
    "maxAdsPerSource": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("himanshu-data/meta-ad-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 = {
    "searchQueries": ["nike"],
    "country": "US",
    "maxAdsPerSource": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("himanshu-data/meta-ad-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 '{
  "searchQueries": [
    "nike"
  ],
  "country": "US",
  "maxAdsPerSource": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call himanshu-data/meta-ad-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,himanshu-data/meta-ad-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/ZMPDCZzpxVxIzKp5x/builds/SfUJMNNSiKV7dvcyk/openapi.json