# Meta (Facebook) Ad Library Scraper (`mikolabs/facebook-ad-library-scraper`) Actor

Scrape the Meta Ad Library by keyword, Facebook Page ID, Ad ID, or direct Ad Library URL. Extract ad copy, CTA, links, images, videos, campaign dates, and other structured data from Facebook and Instagram ads.

- **URL**: https://apify.com/mikolabs/facebook-ad-library-scraper.md
- **Developed by:** [Mikolabs](https://apify.com/mikolabs) (community)
- **Categories:** Social media, Lead generation, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.20 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 (Facebook) Ad Library Scraper — Facebook & Instagram Ads Extractor by Mikolabs

Scrape the Meta Ad Library (Facebook Ad Library) at scale. Extract ad copy, images, video URLs, advertiser details, and creative data from Facebook and Instagram ads — no Meta account, no API key, no approval process required. Export to JSON, CSV, or Excel in minutes.

### What does Meta (Facebook) Ad Library Scraper do?

**Meta (Facebook) Ad Library Scraper** by Mikolabs extracts structured ad data from Meta's public Ad Library. Point it at a keyword, a Facebook Page ID, a specific Ad ID, or a raw Ad Library URL, and it returns clean, structured records — ad creative body, image and video URLs, advertiser name, CTA text and links, platform reach, and delivery dates.

Use it to research competitor Facebook and Instagram ads, monitor brand advertising trends, build ad intelligence datasets, or feed structured ad data into AI/analytics pipelines — all without a Facebook account or Meta developer approval.

Unlike the official Meta Ad Library API (limited to political/issue ads in the EU, gated behind identity verification and a 200 requests/hour cap), this scraper works on **any public ad, targeted at any country, with no account required**.

### Two ways to run it

#### Option A — Direct URLs

Paste one or more complete Facebook Ad Library URLs (from `facebook.com/ads/library`) into `startUrls`. When this field is filled, every other parameter is ignored and the scraper runs exactly what you searched for in your browser.

#### Option B — Auto-build from parameters

Leave `startUrls` empty and instead supply:

- **Search Keywords** (`searchQueries`) — e.g. `"nike"`, `"running shoes"`
- **Facebook Page IDs** (`pageIds`) — numeric IDs to pull every ad from a specific brand page
- **Specific Ad IDs** (`adIds`) — target individual ads directly

Each keyword, Page ID, or Ad ID you provide is launched as its own search and run concurrently (controlled by `maxConcurrency`), so you can batch dozens of brands or keywords in a single actor run.

### What data can you extract?

Every ad result includes the following structured fields:

| Field | Description |
|---|---|
| `libraryID` | Ad Archive ID — unique identifier for historical lookup |
| `brand` | Advertiser page name |
| `industry` | Advertiser industry/category, when available |
| `active` | Whether the ad is currently running (`true`/`false`) |
| `platforms` | Where the ad runs — `facebook`, `instagram`, `messenger`, `audience_network` |
| `totalPlatforms` | Number of platforms the ad runs on |
| `similarAdCount` | Number of creative variants in the same ad group |
| `multipleVersions` | `true` if the ad has multiple creative variants |
| `body` | Full ad copy / creative text |
| `linkTitle` | Headline of the link card |
| `linkUrl` | Destination URL from the ad |
| `linkDescription` | Caption / description from the link card |
| `ctaText` | Call-to-action button text (e.g. "Shop Now", "Install Now") |
| `ctaUrl` | CTA destination URL |
| `images` | Direct URLs to all ad image creatives |
| `videos` | Direct URLs to all ad video creatives |
| `startDate` | Ad delivery start date (Unix timestamp) |
| `endDate` | Ad delivery end date, or empty if still active |
| `format` | Creative format — `video`, `image`, or `unknown` |

### Filters & targeting

| Parameter | Description |
|---|---|
| `country` | ISO 2-letter country code for ad targeting (e.g. `US`, `GB`, `IN`) — required in Option B |
| `activeStatus` | `active`, `inactive`, or `all` |
| `adType` | `all`, `political_and_issue_ads`, `housing`, `employment`, or `credit` |
| `mediaType` | `all`, `image`, `video`, or `meme` |
| `isTargetedCountry` | If `true`, only returns ads that specifically target your chosen country |
| `contentLanguages` | Restrict results to specific languages (e.g. `en`, `es`, `it`) |
| `sortMode` | Sort by `total_impressions` (reach), `relevance`, or `start_date` |
| `sortDirection` | `desc` (highest first) or `asc` |

### How to scrape the Meta Ad Library

#### Option A: Paste a Facebook Ad Library URL

1. Visit [facebook.com/ads/library](https://www.facebook.com/ads/library) and search with your desired filters (keyword, brand, or `view_all_page_id=...` for a specific page)
2. Copy the URL from your browser address bar
3. Paste it into **Facebook Ad Library URLs (Direct)** (`startUrls`) — you can add more than one
4. Click **Start**

#### Option B: Build the search from parameters

1. Open **Meta (Facebook) Ad Library Scraper** on Apify and click **Try for free**
2. Enter your **Target Country** (`country`)
3. Add one or more **Search Keywords**, **Facebook Page IDs**, or **Specific Ad IDs**
4. Apply filters — ad status, ad category, media type, languages, sort order
5. Set **Maximum Ads to Scrape** (`maxItems`)
6. Click **Start**
7. When the run finishes, click **Export** to download JSON, CSV, or Excel

### Input example

```json
{
  "country": "US",
  "searchQueries": ["nike"],
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "isTargetedCountry": false,
  "sortMode": "total_impressions",
  "sortDirection": "desc",
  "maxItems": 100,
  "maxConcurrency": 1,
  "requestHandlerTimeoutSecs": 900,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

### Output example

Each result is a clean, flat ad object ready for analysis:

```json
{
  "libraryID": "971661872066048",
  "brand": "H&M",
  "industry": "",
  "active": true,
  "platforms": [],
  "totalPlatforms": 0,
  "similarAdCount": 2,
  "multipleVersions": true,
  "body": "{{product.brand}}",
  "linkTitle": "{{product.name}}",
  "linkUrl": "http://itunes.apple.com/app/id834465911",
  "linkDescription": "itunes.apple.com",
  "ctaText": "Install now",
  "ctaUrl": "http://itunes.apple.com/app/id834465911",
  "images": [],
  "videos": [],
  "startDate": "1777273200",
  "endDate": "1785913200",
  "format": "unknown"
}
```

You can download the full dataset in **JSON, CSV, Excel, or HTML** directly from the Apify Console, or fetch it programmatically via the API.

### Pricing

This actor is **pay-per-result** — just **$0.20 per 1,000 ads** scraped, with **no actor start fee**. You only pay for the results you actually get. The Apify Free plan includes monthly platform credits, which is enough to scrape thousands of ads at no extra cost.

### How to use the API

Run this scraper programmatically to feed Meta ad data into your own apps, dashboards, or automation pipelines.

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_API_TOKEN")

run_input = {
    "country": "US",
    "searchQueries": ["nike", "adidas"],
    "activeStatus": "active",
    "maxItems": 200,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"]
    },
}

run = client.actor("mikolabs/meta-ads").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### JavaScript / Node.js

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

const client = new ApifyClient({ token: 'YOUR_APIFY_API_TOKEN' });

const input = {
    country: 'US',
    searchQueries: ['nike', 'adidas'],
    activeStatus: 'active',
    maxItems: 200,
    proxyConfiguration: { useApifyProxy: true, apifyProxyGroups: ['RESIDENTIAL'] },
};

const run = await client.actor('mikolabs/meta-ads').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

For the full API reference, see the **API** tab on this actor's page.

### Advanced settings

| Setting | Description |
|---|---|
| `maxItems` | Maximum number of ads to collect. Stops immediately when reached (default: 30, minimum: 1) |
| `maxConcurrency` | Number of parallel browser tabs (1–10). We recommend 1–2 for best stability |
| `requestHandlerTimeoutSecs` | Max seconds allowed to scroll a single URL before moving on (default: 900 / 15 min, handles lists with thousands of ads) |
| `proxyConfiguration` | Residential proxy config — required to reliably bypass Facebook's anti-scraping measures |

### Why use this instead of the official Meta Ad Library API?

| Feature | Mikolabs Meta (Facebook) Ad Library Scraper | Official Meta Ad Library API |
|---|---|---|
| **Ad types** | All ads — commercial, political, housing, employment, credit | Political/issue ads only |
| **Countries** | Any country you target | Limited coverage, EU-focused for political ads |
| **Rate limit** | No hard limit | 200 calls/hour |
| **Approval required** | No | Yes — identity verification required |
| **Meta account needed** | Not required | Required |
| **Creative data** | Full — images, videos, ad copy, CTA, links | Limited |
| **Export formats** | JSON, CSV, Excel, HTML | JSON only |
| **Input flexibility** | Direct URL, keyword, Page ID, or Ad ID | Query parameters only |

### Use cases

- **Competitor ad research** — see exactly what creatives, copy, and landing pages competitors run on Facebook and Instagram
- **Facebook & Instagram ad spy tool** — monitor any brand's Meta advertising activity without manual browsing
- **Market research** — surface ad copy trends, creative formats, and messaging patterns by keyword, industry, or country
- **Ad creative inspiration** — browse top-performing ads by keyword, niche, or brand
- **eCommerce & dropshipping research** — find products being advertised heavily on Facebook and Instagram
- **Lead generation** — identify actively advertising businesses in any niche or market
- **Political ad monitoring** — track political and issue-based ads for journalism or compliance
- **Brand monitoring** — track how brands present themselves across paid channels on Meta
- **AI training data** — feed structured ad creative data into models for analysis or classification
- **Marketing analytics** — build dashboards tracking competitor ad activity and creative rotation over time

### FAQ

**Do I need a Facebook account or Meta API key?**
No. The Meta Ad Library is publicly accessible without login. This scraper requires no Facebook credentials, Meta API keys, access tokens, or approval process.

**What proxy should I use?**
A residential proxy is required for reliable scraping — Facebook blocks datacenter IPs. The default `proxyConfiguration` uses Apify's Residential Proxy group, which works reliably for most use cases.

**Can I scrape ads from multiple countries at once?**
Yes. Run separate searches per country by setting `country` and re-running, or queue multiple direct URLs targeting different countries in `startUrls`.

**Can I scrape Instagram ads?**
Yes. The Meta Ad Library includes ads running across Meta platforms — Facebook, Instagram, Messenger, and Audience Network. Instagram ads appear with `"instagram"` in the `platforms` field.

**Can I target a specific brand directly?**
Yes. Provide the brand's numeric Facebook Page ID in `pageIds`, or paste a Page's Ad Library URL (containing `view_all_page_id=...`) into `startUrls`.

**Can I look up one specific ad?**
Yes. Provide its numeric ID in `adIds` to fetch that ad directly.

**What if the run is interrupted mid-scrape?**
Data is not lost — any ads already collected before the interruption remain available in the run's default dataset.

**How many ads can I scrape per run?**
There's no hard cap. Set `maxItems` to any value; actual throughput depends on proxy quality, `maxConcurrency`, and Facebook's own rate limiting.

**Can I use this as an unofficial Meta Ads API?**
Yes. Run this scraper programmatically via the Apify API and get structured ad data back in JSON — without the account, approval, and rate-limit restrictions of Meta's official API.

### Support

Found a bug, got a feature request, or have a question? Open an issue on the **Issues** tab on this actor's page.

Built by [Mikolabs](https://apify.com/mikolabs) — fast, reliable, production-ready Apify actors for data extraction at scale.

# Actor input Schema

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

Provide one or more Facebook Ad Library URLs directly. If provided, all parameter fields below are ignored. Leave empty to build the URL from parameters instead.

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

ISO 2-letter country code for ad targeting (e.g. US, GB, IN, CA). Required if not using direct URLs.

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

List of keywords to search (e.g., 'nike', 'running shoes'). One search is launched concurrently per keyword.

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

List of numeric Page IDs to target specific brands (e.g., 108047081396228). Launches concurrently.

## `adIds` (type: `array`):

List of specific numeric Ad IDs to target directly.

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

Filter ads by campaign status (Active, Inactive, or All).

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

Filter by Facebook ad categories (e.g. Political, Credit, Housing, or standard ads).

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

Scrape ads matching specific media formats (Images, Videos, or Memes).

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

Only return ads that specifically target your chosen Target Country.

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

Restrict results to specific languages (e.g. 'en', 'es', 'it'). Leave blank for all.

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

Define which metric determines results ordering.

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

Descending (highest first) or Ascending.

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

Stop scraping when you hit this total number of ads. The minimum is 1.

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

Number of browser tabs to run concurrently. We recommend 1-2 for best stability.

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

Max seconds allowed to scroll a single URL. Default of 900 (15m) handles lists with thousands of ads.

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

Residential Proxy is required to bypass Facebook blocks. Select Apify Proxy or use custom proxies.

## Actor input object example

```json
{
  "country": "US",
  "searchQueries": [
    "nike"
  ],
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "isTargetedCountry": false,
  "sortMode": "total_impressions",
  "sortDirection": "desc",
  "maxItems": 30,
  "maxConcurrency": 1,
  "requestHandlerTimeoutSecs": 900,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Overview of all scraped ads with key metrics and details

## `allAds` (type: `string`):

Complete dataset with all fields including metadata, images, and videos

# 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 = {
    "country": "US",
    "searchQueries": [
        "nike"
    ],
    "maxItems": 30,
    "maxConcurrency": 1,
    "requestHandlerTimeoutSecs": 900
};

// Run the Actor and wait for it to finish
const run = await client.actor("mikolabs/facebook-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 = {
    "country": "US",
    "searchQueries": ["nike"],
    "maxItems": 30,
    "maxConcurrency": 1,
    "requestHandlerTimeoutSecs": 900,
}

# Run the Actor and wait for it to finish
run = client.actor("mikolabs/facebook-ad-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 '{
  "country": "US",
  "searchQueries": [
    "nike"
  ],
  "maxItems": 30,
  "maxConcurrency": 1,
  "requestHandlerTimeoutSecs": 900
}' |
apify call mikolabs/facebook-ad-library-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jq9qSgFyN3GCeZj6u/builds/qbdAnDbd6EYD7EwoI/openapi.json