# Facebook Ads Library Scraper (`attainable_readiness/facebook-ads-library-scraper`) Actor

Fast & reliable scraper for Meta Ads Library. Extract full ad details, media links (images/videos), primary texts, CTAs, landing pages, and full raw snapshots. Supports filtering by keyword, page ID, country, and date presets.

- **URL**: https://apify.com/attainable\_readiness/facebook-ads-library-scraper.md
- **Developed by:** [Michael Mikaelian](https://apify.com/attainable_readiness) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $3.50 / 1,000 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

## Facebook Ads Library Creative Scraper

An Apify Actor that scrapes **commercial ad creatives** from Meta Ads Library using **Playwright browser automation with live GraphQL response interception** — bypassing the official API restriction that hides commercial ads.

***

### Why This Actor Exists

The official Meta Ads Library API only exposes **political, social issue, housing, employment, and credit ads**. Commercial ads — the most valuable category for competitive intelligence — are intentionally hidden from the API.

This Actor solves that by opening the actual Ads Library web UI in a real Chromium browser, then **intercepting the live GraphQL responses** that Facebook's own JavaScript fires to load the ad cards. You get exactly what the UI shows, parsed into clean structured JSON.

***

### Key Features

- **Full commercial creative access:** Captures brand ads that the official API never returns.
- **Dual search modes:** Search by **keyword/brand** OR browse all ads from a **specific Facebook Page ID**.
- **Rich creative data:** Images, videos, carousels with per-card data, CTA type, ad copy, link title/description.
- **Audience insights:** Spend estimates, impression ranges, demographic distribution, regional delivery, EU DSA reach.

***

### Input Parameters

| Field | Type | Description | Default |
|---|---|---|---|
| `start_url` | `String` | Direct URL from the Facebook Ads Library with search filters. If provided, other filters are ignored. | `""` |
| `search_query` | `String` | Keyword or brand name to search | `""` |
| `country` | `String` | ISO 2-letter country code or `"ALL"` | `"ALL"` |
| `ad_type` | `String` | `ALL`, `POLITICAL_AND_ISSUE_ADS`, `HOUSING_ADS`, `EMPLOYMENT_ADS`, `CREDIT_ADS` | `"ALL"` |
| `active_status` | `String` | `ALL`, `ACTIVE`, `INACTIVE` | `"ALL"` |
| `media_type` | `String` | `ALL`, `image`, `meme`, `video`, `none` | `"ALL"` |
| `page_ids` | `Array<String>` | Filter by specific Facebook Page IDs | `null` |
| `date_preset` | `String` | `ALL`, `last_7_days`, `last_30_days`, `last_90_days` | `"ALL"` |
| `max_ads` | `Integer` | Maximum ad creatives to collect | `100` |
| `scroll_pause_ms` | `Integer` | Pause between scroll steps in ms (increase for slow connections) | `2000` |

#### Input Example — Direct Start URL

```json
{
  "start_url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&media_type=video",
  "max_ads": 150
}
```

#### Input Example — Keyword Search

```json
{
  "search_query": "Nike",
  "country": "US",
  "active_status": "ACTIVE",
  "media_type": "video",
  "max_ads": 200
}
```

#### Input Example — Scrape All Ads from a Specific Page

```json
{
  "page_ids": ["123456789"],
  "active_status": "ALL",
  "max_ads": 500
}
```

***

### Output Data Structure

Each record in the Dataset represents a detailed ad archive object exactly matching the Meta Ads Library GraphQL schema.

#### Sample Output (JSON)

```json
[
  {
    "ad_archive_id": "1702938977100376",
    "collation_count": null,
    "collation_id": null,
    "is_active": true,
    "page_id": "15087023444",
    "page_is_deleted": false,
    "snapshot": {
      "branded_content": null,
      "page_id": "15087023444",
      "page_is_deleted": false,
      "page_profile_uri": "https://www.facebook.com/nike/",
      "root_reshared_post": null,
      "byline": null,
      "disclaimer_label": null,
      "page_name": "Nike",
      "page_profile_picture_url": "https://scontent.fdnk2-1.fna.fbcdn.net/v/...",
      "event": null,
      "caption": "itunes.apple.com",
      "cta_text": "Install now",
      "cards": [
        {
          "body": "Bring sports more fully into your day with the Nike App.",
          "cta_type": "INSTALL_MOBILE_APP",
          "caption": "itunes.apple.com",
          "link_description": "₱5,039",
          "link_url": "https://www.nike.com/ph/t/...",
          "title": "Cosmic Unity 3 Basketball Shoes",
          "cta_text": "Install Now",
          "original_image_url": "https://scontent.fdnk2-1.fna.fbcdn.net/v/...",
          "resized_image_url": "https://scontent.fdnk2-1.fna.fbcdn.net/v/...",
          "watermarked_resized_image_url": ""
        }
      ],
      "body": {
        "text": "Bring sports more fully into your day with the Nike App."
      },
      "cta_type": "INSTALL_MOBILE_APP",
      "display_format": "DPA",
      "link_description": null,
      "link_url": "http://itunes.apple.com/app/id1095459556",
      "images": [],
      "page_categories": [
        "Sportswear",
        "Product/service"
      ],
      "page_like_count": 39551236,
      "title": "{{product.name}}",
      "videos": [],
      "is_reshared": false
    },
    "has_user_reported": false,
    "report_count": null,
    "menu_items": [],
    "state_media_run_label": null,
    "page_name": "Nike",
    "impressions_with_index": {
      "impressions_text": null,
      "impressions_index": -1
    },
    "gated_type": "ELIGIBLE",
    "categories": [
      "UNKNOWN"
    ],
    "is_aaa_eligible": false,
    "contains_digital_created_media": false,
    "reach_estimate": null,
    "currency": "",
    "spend": null,
    "end_date": "1788073200",
    "publisher_platform": [
      "FACEBOOK",
      "INSTAGRAM",
      "AUDIENCE_NETWORK",
      "MESSENGER"
    ],
    "start_date": "1744009200",
    "contains_sensitive_content": false,
    "total_active_time": null,
    "regional_regulation_data": {
      "finserv": {
        "is_deemed_finserv": false,
        "is_limited_delivery": false
      },
      "tw_anti_scam": {
        "is_limited_delivery": false
      }
    },
    "hide_data_status": "NONE",
    "fev_info": null,
    "ad_id": null,
    "targeted_or_reached_countries": [],
    "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&view_all_page_id=15087023444",
    "total": 3357,
    "position": 1,
    "ads_count": 1,
    "start_date_formatted": "2025-04-07 07:00:00",
    "end_date_formatted": "2026-08-30 07:00:00",
    "ad_library_url": "https://www.facebook.com/ads/library/?id=1702938977100376",
    "scraped_at": "2026-08-30T15:54:48.621419+00:00"
  }
]
```

***

### Common Use Cases

- **Competitive intelligence:** Monitor competitors' ad strategies, messaging, and creative formats.
- **Creative research:** Find winning ad creatives in your niche for inspiration and benchmarking.
- **Spend tracking:** Estimate competitor budgets based on spend range metadata.
- **Audience analysis:** Understand demographic targeting through distribution data.
- **Creative library building:** Build searchable repositories of brand ads for analysis.
- **Agency reporting:** Deliver creative performance benchmarks to clients.

# Actor input Schema

## `start_url` (type: `string`):

Direct Facebook Ads Library URL (e.g. https://www.facebook.com/ads/library/?active\_status=active...). If provided, other filters are ignored.

## `search_query` (type: `string`):

Keyword or brand name to search in Meta Ads Library. Leave empty to browse by page only.

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

ISO 2-letter country code to filter ads by country (e.g. 'US', 'GB', 'DE'). Use 'ALL' for all countries.

## `ad_type` (type: `string`):

Type of ads to collect.

## `active_status` (type: `string`):

Filter ads by their current delivery status.

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

Filter ads by media content type.

## `page_ids` (type: `array`):

Limit results to specific Facebook Page IDs. Leave empty to search all pages.

## `date_preset` (type: `string`):

Filter ads by when they started running.

## `max_ads` (type: `integer`):

Maximum number of ad creatives to collect in this run.

## `scroll_pause_ms` (type: `integer`):

Milliseconds to wait between scroll steps. Increase if ads are not loading fast enough.

## Actor input object example

```json
{
  "search_query": "Nike",
  "country": "ALL",
  "ad_type": "ALL",
  "active_status": "ALL",
  "media_type": "ALL",
  "date_preset": "ALL",
  "max_ads": 100,
  "scroll_pause_ms": 2000
}
```

# Actor output Schema

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

Dataset containing scraped Meta Ads Library ad creatives with page, spend and audience data.

# 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 = {
    "start_url": "",
    "search_query": "Nike",
    "country": "ALL"
};

// Run the Actor and wait for it to finish
const run = await client.actor("attainable_readiness/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 = {
    "start_url": "",
    "search_query": "Nike",
    "country": "ALL",
}

# Run the Actor and wait for it to finish
run = client.actor("attainable_readiness/facebook-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 '{
  "start_url": "",
  "search_query": "Nike",
  "country": "ALL"
}' |
apify call attainable_readiness/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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