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

Ultra-fast Facebook Ads Library scraper with advanced filtering. Extract ads from Meta Ads Library in seconds! Perfect for competitor analysis, market research, and ad intelligence.

- **URL**: https://apify.com/apipi/facebook-ad-library-scraper.md
- **Developed by:** [ApiPi](https://apify.com/apipi) (community)
- **Categories:** Social media, E-commerce, Automation
- **Stats:** 250 total users, 2 monthly users, 100.0% runs succeeded, 5 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

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

**Ultra-fast** Facebook Ads Library scraper with advanced filtering. Extract ads from Meta Ads Library in seconds! Perfect for competitor analysis, market research, and ad intelligence. 📊

Scrape detailed ad data from Facebook Ad Library API (Meta Ads Library API) with support for all countries, languages, and ad types. Get images, videos, ad copy, targeting data, and performance metrics in clean JSON format. The fastest Facebook Ad Library scraper on Apify! ⚡

### Why Choose This Scraper? ⚡

- 🔥 **Lightning Fast** - Scrape 100+ ads in under 10 seconds
- 🎯 **Advanced Filtering** - Filter by language, media type, date range, and more
- 🌍 **All Countries Supported** - Works with any country's Facebook Ad Library
- 📊 **Rich Data Extraction** - Get complete ad details including creatives, targeting, and performance
- 🔄 **Automatic Pagination** - Scrape unlimited ads with smart pagination
- 💎 **Clean JSON Output** - Well-structured data ready for analysis

### Features ✨

- ✅ **Meta Ads Library API Access** - Direct access to Facebook Ad Library data
- ✅ **Multiple Search Types** - Exact phrase or keyword matching
- ✅ **Media Filtering** - Filter by images, videos, or all media types
- ✅ **Date Range Support** - Target specific ad campaign periods
- ✅ **Language Detection** - Filter ads by language
- ✅ **Bulk Scraping** - Extract up to 1000+ ads per run
- ✅ **Real-time Data** - Get the latest active ads from Facebook Ads Library

### 📊 What Data You Get from Facebook Ads Library

Extract comprehensive ad intelligence from the Facebook Ad Library API:

- **Ad Identification**: Archive ID, page ID, ad status
- **Creative Assets**: Ad copy, images URLs, video links, carousel cards
- **Campaign Details**: Start date, end date, active status
- **Targeting Data**: Publisher platforms (Facebook, Instagram, Messenger, Audience Network)
- **Performance Metrics**: Impressions range, reach estimates
- **Page Information**: Page name, category, profile picture, likes count
- **Call-to-Action**: CTA text, CTA type, destination URL
- **Rich Snapshot**: Complete ad creative in JSON format

### 🚀 Quick Start - Facebook Ad Library Scraper

#### Required Input

- **query** (required): Search keyword, brand name, or phrase to find in Facebook Ads Library

#### Optional Filters for Meta Ads Library

- **country**: Country code (default: `US`) - Search any country's Facebook Ad Library
- **max_results**: Number of ads to scrape (default: `30`, max: `1000`)
- **keyword_type**: `KEYWORD_EXACT_PHRASE` or `keyword_unordered`
- **languages**: Filter by language - e.g., `["en", "es"]` for English and Spanish ads
- **media_type**: `all`, `IMAGE` (images only), or `VIDEO` (videos only)
- **start_date_min**: Filter ads by start date (format: `YYYY-MM-DD`)
- **start_date_max**: Filter ads by end date (format: `YYYY-MM-DD`)

### 📝 Input Examples

#### Basic Search

```json
{
  "query": "Nike",
  "country": "US",
  "max_results": 100
}
```

#### Search with Filters

```json
{
  "query": "running shoes",
  "country": "US",
  "max_results": 200,
  "keyword_type": "KEYWORD_EXACT_PHRASE",
  "languages": ["en"],
  "media_type": "IMAGE",
  "start_date_min": "2024-01-01",
  "start_date_max": "2024-12-31"
}
```

#### Multi-language Search

```json
{
  "query": "hotel",
  "country": "ES",
  "max_results": 150,
  "languages": ["en", "es", "de"]
}
```

#### Video Ads Only

```json
{
  "query": "brand campaign",
  "country": "US",
  "max_results": 50,
  "media_type": "VIDEO"
}
```

### 🌍 Supported Countries

Use standard ISO country codes:

- `US` - United States
- `GB` - United Kingdom
- `DE` - Germany
- `FR` - France
- `ES` - Spain
- `IT` - Italy
- `CA` - Canada
- `AU` - Australia
- And many more...

### 🗣️ Supported Languages

Filter by language using ISO 639-1 codes:

- `en` - English
- `es` - Spanish
- `de` - German
- `fr` - French
- `it` - Italian
- `pt` - Portuguese
- `ru` - Russian
- `zh` - Chinese
- `ja` - Japanese
- `ko` - Korean
- And others...

### 📦 Output Format

```json
  {
    "ad_archive_id": "1805241386799255",
    "page_id": "112663631773139",
    "page_name": "Beautiful-sunflower.be",
    "is_active": true,
    "start_date": 1761634800,
    "end_date": 1761634800,
    "snapshot": {
      "branded_content": null,
      "page_id": "112663631773139",
      "page_is_deleted": false,
      "page_profile_uri": "https://www.facebook.com/100090208388488/",
      "root_reshared_post": null,
      "byline": null,
      "disclaimer_label": null,
      "page_name": "Beautiful-sunflower.be",
      "page_profile_picture_url": "https://scontent-waw2-2.xx.fbcdn.net/v/t39.35426-6/571129675_820183734271297_815979828536297806_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=sORaBlqgqcAQ7kNvwHmCXMa&_nc_oc=AdkftOJHyhsAiaL06ibnoaPefvj4KHZMOabWSnvu5nSN5_RfqLWijQZXYSTg2wcPSwprNi1CGNb3O9Nv9pvbw-qU&_nc_zt=14&_nc_ht=scontent-waw2-2.xx&_nc_gid=kfx9Ulbb4t_XsjfIElJ7ig&oh=00_AfcEqUiFACRa8k8dj6KdGU0IljPPvDtTVyM59Cnp-6Aq5g&oe=69069F8E",
      "event": null,
      "caption": "beautiful-sunflower.com",
      "cta_text": "Jetzt kaufen",
      "cards": [],
      "body": {
        "text": "🚴‍♂️ Ride into the spirit of the season!\nThe Grand Cycling Adventure Advent Calendar 2025 brings 24 days of pure excitement inspired by the world’s greatest race — a tribute to endurance, freedom, and passion on two wheels."
      },
      "cta_type": "SHOP_NOW",
      "display_format": "IMAGE",
      "link_description": "🚴‍♂️🌟 The Tour de France Advent Calendar 2025 Collector’s Edition is officially launched, celebrating the glory and passion of cycling fans across the world💥 Each drawer unveils exclusive Tour de France treasures — from mini racing bikes and team helmets to champion figu...",
      "link_url": "https://www.beautiful-sunflower.com/products/tour-de-france-advent-calendar-2025-2173411442236",
      "images": [
        {
          "image_crops": [],
          "original_image_url": "https://scontent-waw2-1.xx.fbcdn.net/v/t39.35426-6/571164864_1886139212287452_6157224743190712048_n.jpg?_nc_cat=104&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ZbsD2y3CgM8Q7kNvwEziJLk&_nc_oc=Admqc3TGp5A4uu3YG6dMGl_Qyg_k3_fItFngth9wHErpuZcBqDmTQANf7S8UHhuZBoDzhvSdIfCaMEvZx14mYAsE&_nc_zt=14&_nc_ht=scontent-waw2-1.xx&_nc_gid=kfx9Ulbb4t_XsjfIElJ7ig&oh=00_AfcKrxy3oWf7hZisQ_gS8LzqCr34weNELATMJSphoY5u5g&oe=6906A6C2",
          "resized_image_url": "https://scontent-waw2-2.xx.fbcdn.net/v/t39.35426-6/571201344_1782071335815707_1285150469390277666_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=5I07KULskHgQ7kNvwHfnNZJ&_nc_oc=AdlohxSgOWrvadO05cWac2dEf14p6WSEk8cCF78GvnpJ6o6b23-WpxJc5UeuG_ZBOmbK3swu1FN8GF0H03UxVZkb&_nc_zt=14&_nc_ht=scontent-waw2-2.xx&_nc_gid=kfx9Ulbb4t_XsjfIElJ7ig&oh=00_AfcXnT3pAJgYB2mD-A0A3XX8pzQefMWHhNUsWXjh2zJrvg&oe=6906BA28",
          "watermarked_resized_image_url": ""
        }
      ],
      "page_categories": [
        "Product/service"
      ],
      "page_like_count": 1301,
      "title": "Tour de France Advent Calendar 2025",
      "videos": [],
      "is_reshared": false,
      "extra_links": [],
      "extra_texts": [],
      "extra_images": [],
      "extra_videos": [],
      "country_iso_code": null,
      "brazil_tax_id": null,
      "additional_info": null,
      "ec_certificates": []
    },
    "publisher_platform": [
      "FACEBOOK",
      "INSTAGRAM",
      "AUDIENCE_NETWORK",
      "MESSENGER",
      "THREADS"
    ],
    "impressions": {
      "impressions_text": null,
      "impressions_index": -1
    },
    "currency": ""
  },
```

### 💡 Use Cases for Facebook Ads Library Data

#### 🎯 Competitive Intelligence

Monitor competitors' Facebook advertising strategies in real-time. Track their ad copy, creative assets, and campaign frequency using Meta Ads Library data.

#### 📊 Market Research

Analyze advertising trends across your industry. Discover what products, messages, and creative formats perform best in the Facebook Ad Library.

#### 🎨 Creative Inspiration

Study successful ad campaigns from top brands. Extract images, videos, and copy from the Facebook Ads Library for creative inspiration.

#### 📈 Campaign Tracking

Track brand campaigns over time using the Facebook Ad Library API. Monitor ad launch dates, duration, and creative variations.

#### 🌍 Regional Analysis

Compare advertising strategies across different countries. See how brands adapt their messages for different markets using Meta Ads Library.

#### 🔍 Brand Monitoring

Get alerts when specific brands launch new campaigns. Track your own brand mentions in the Facebook Ad Library.

### ⚡ Performance - Ultra-Fast Facebook Ad Library Scraping

#### Speed Benchmarks 🚀

- **30 ads** → Less than 3 seconds ⚡
- **100 ads** → Under 10 seconds 🔥
- **500 ads** → Approximately 30 seconds 💨
- **1000 ads** → Around 1 minute ⏱️

#### Why So Fast?

- ✅ Optimized Meta Ads Library API requests
- ✅ Smart pagination with automatic cursor management
- ✅ Parallel data processing
- ✅ Minimal overhead - direct JSON output
- ✅ No browser automation needed

#### Reliability

- 🛡️ Built-in error handling and automatic retries
- 🔄 Handles Facebook Ad Library rate limits automatically
- 📊 Consistent data quality
- ✅ 99%+ success rate

### 📋 Best Practices for Facebook Ad Library Scraping

#### 1. Optimize Your Queries 🎯

Use specific brand names or product keywords for better Facebook Ads Library results:

- ✅ **Good**: `"Nike Air Max"` - specific product
- ✅ **Better**: `"Nike"` - brand name
- ❌ **Too broad**: `"shoes"` - generic term

#### 2. Start Small, Scale Up 📈

Test with 30-50 ads first, then increase to 100-500+ for comprehensive Meta Ads Library data extraction.

#### 3. Use Smart Filters 🔍

Leverage advanced filtering for precise Facebook Ad Library data:

- **Languages**: Target specific markets (`["en", "es"]`)
- **Media Type**: Filter for `IMAGE` or `VIDEO` ads only
- **Date Range**: Focus on recent campaigns or specific periods
- **Countries**: Scrape from any country's Facebook Ad Library

#### 4. Regular Monitoring 📊

Set up daily/weekly scrapes to track competitors' Facebook advertising strategies over time.

### ⚠️ Limitations

- Rate limiting: ~1 request per second
- Some ads may have limited data availability
- Date filters apply to ad start dates
- Historical data availability varies by region

***

**Tags**: `facebook-ad-library` `facebook-ads` `meta-ads` `ad-scraper` `competitive-intelligence` `market-research` `facebook-api` `meta-api` `ad-intelligence` `facebook-advertising`

# Actor input Schema

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

Search query (company name, keywords, etc.). This field is required.

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

Country code (US, GB, DE, etc.)

## `max_results` (type: `integer`):

Maximum number of ads to scrape

## `keyword_type` (type: `string`):

Type of keyword search

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

Filter by languages (e.g., \['en', 'es']). Leave empty for all languages.

## `media_type` (type: `string`):

Filter by media type

## `start_date_min` (type: `string`):

Start date in YYYY-MM-DD format (e.g., 2024-01-01). Leave empty for no date filter.

## `start_date_max` (type: `string`):

End date in YYYY-MM-DD format (e.g., 2024-12-31). Leave empty for no date filter.

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

Proxy settings for requests. Recommended for better reliability and to avoid blocks.

## Actor input object example

```json
{
  "query": "Nike",
  "country": "US",
  "max_results": 100,
  "keyword_type": "KEYWORD_EXACT_PHRASE",
  "languages": [
    "en"
  ],
  "media_type": "all",
  "start_date_min": "2024-01-01",
  "start_date_max": "2024-12-31",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("apipi/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 = { "proxyConfiguration": { "useApifyProxy": True } }

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apipi/facebook-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/uMnsf6khYz0VsDGlg/builds/euQf0WpWvzFunLrcA/openapi.json