# Facebook Ads Library Scraper — Meta Ad Library API (`aurumworks/facebook-ads-library`) Actor

Extract ads from the Meta Ad Library using the official Graph API. Search by keyword or advertiser, filter by country and status. Get ad creatives, copy, spend ranges, impressions, demographics, and platform data. Auto-pagination, flat output schema, CSV/Excel export.

- **URL**: https://apify.com/aurumworks/facebook-ads-library.md
- **Developed by:** [Aryan Saxena](https://apify.com/aurumworks) (community)
- **Categories:** Automation, E-commerce, Other
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Scraper — Extract Ads from Meta Ad Library

**Pull competitor ads from the Meta Ad Library at scale.** Search by keyword or advertiser, filter by country and status, and get structured data including ad copy, creatives, spend ranges, impressions, demographics, and platform breakdowns.

This actor uses the official Meta Graph API for reliable, structured results. It handles pagination automatically — the API returns only 100 ads per page, but this actor follows every cursor to get thousands of results in a single run.

### Why use this actor instead of the API directly?

- **Auto-pagination** — the Meta API caps at 100 ads per page. This actor follows all pagination cursors automatically.
- **Clean, flat output** — the API returns deeply nested JSON (arrays inside arrays). This actor flattens everything into a simple, export-ready schema.
- **No coding needed** — fill in the form, click Start, export to CSV or Excel.
- **Scheduling** — set it to run daily or weekly to monitor competitor ads over time.
- **Integrations** — connect to Google Sheets, Slack, Zapier, or webhooks via Apify.

### How to get a Meta access token

You need a Meta access token to use this actor. Here's how to get one:

1. Go to [Meta Graph API Explorer](https://developers.facebook.com/tools/explorer/)
2. Select your app (or create one at [developers.facebook.com](https://developers.facebook.com))
3. Click **Generate Access Token**
4. Grant the `ads_read` permission when prompted
5. Copy the token and paste it into the actor input

Tokens expire after about 1–2 hours. For long-term use, [generate a long-lived token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/).

### How to use Facebook Ads Library Scraper

1. Click **Try for free** on this page
2. Paste your Meta access token
3. Enter a search keyword (e.g. "running shoes") or a Facebook Page ID
4. Select a country code (e.g. US, GB, DE)
5. Click **Start** and wait for results
6. Download your data as JSON, CSV, or Excel

### Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Access Token | string | **Yes** | Meta Graph API access token |
| Search Query | string | No* | Keywords to search in ads |
| Page ID | string | No* | Facebook Page ID for a specific advertiser |
| Country Code | string | No | Two-letter code (default: US) |
| Ad Type | string | No | all or political_and_issue_ads |
| Ad Status | string | No | active, inactive, or all |
| Max Results | integer | No | Max ads to fetch (default: 100) |

*Either Search Query or Page ID is required.

### Output

```json
{
  "adId": "123456789",
  "pageName": "Nike",
  "pageId": "15087023444",
  "adCreativeBody": "Just Do It. New running shoes available now.",
  "adCreativeLinkTitle": "Shop Nike Running",
  "adCreativeLinkDescription": "Free shipping on orders over $50",
  "adCreationTime": "2025-03-01T08:00:00+0000",
  "deliveryStartTime": "2025-03-01T08:00:00+0000",
  "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=123456789",
  "currency": "USD",
  "spendLower": "100",
  "spendUpper": "499",
  "impressionsLower": "10000",
  "impressionsUpper": "50000",
  "publisherPlatforms": ["facebook", "instagram"],
  "languages": ["en"]
}
````

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Data fields

| Field | Description |
|-------|-------------|
| adId | Unique ad identifier |
| pageName | Advertiser's Facebook Page name |
| adCreativeBody | Main ad copy text |
| adCreativeLinkTitle | Headline text |
| adCreativeLinkDescription | Description below headline |
| adCreationTime | When the ad was created |
| deliveryStartTime | When the ad started running |
| deliveryStopTime | When the ad stopped (if inactive) |
| adSnapshotUrl | Link to view the ad creative |
| spendLower / spendUpper | Estimated spend range |
| impressionsLower / impressionsUpper | Estimated impression range |
| publisherPlatforms | Where the ad ran (facebook, instagram, messenger) |
| languages | Ad languages |
| demographicDistribution | Age and gender breakdown |
| deliveryByRegion | Geographic delivery data |

### How much does it cost to scrape Facebook ads?

Cost depends on the number of ads fetched. A typical run fetching 500 ads costs about **$0.02** in platform usage (API calls are lightweight). The Apify free tier is more than enough for regular use.

### Tips

- **Monitor competitors**: schedule weekly runs with a Page ID to track when competitors launch new ads
- **Keyword research**: search for industry keywords to see what messaging competitors use
- **Multi-country**: run the actor multiple times with different country codes to compare ad strategies across markets
- **Export to Sheets**: use the Google Sheets integration to build a live competitive intelligence dashboard

### Limitations

- A Meta access token is required (free to generate, but expires periodically)
- Spend and impression data are ranges, not exact numbers (this is Meta's policy)
- Some fields may be empty depending on the ad type and region
- Rate limits apply — very large runs (5,000+ ads) may take longer

### FAQ

**Is this legal?**
Yes. The Meta Ad Library is a public transparency tool. This actor uses the official Graph API, which Meta provides specifically for programmatic access.

**Why do I need an access token?**
Meta requires authentication for API access. The token is free to generate and takes about 30 seconds.

**My token expired. What do I do?**
Generate a new one at the [Graph API Explorer](https://developers.facebook.com/tools/explorer/). For long-term use, create a long-lived token.

**I found a bug or have a feature request.**
Please open an issue in the Issues tab.

# Actor input Schema

## `accessToken` (type: `string`):

Meta Graph API access token with ads\_read permission. Get one at https://developers.facebook.com/tools/explorer/

## `searchQuery` (type: `string`):

Keywords to search for in ads (e.g. 'running shoes', 'SaaS')

## `pageId` (type: `string`):

Facebook Page ID to get all ads from a specific advertiser

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

Two-letter country code (e.g. US, GB, IN, AE, DE)

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

Type of ads to search

## `adStatus` (type: `string`):

Filter by ad status

## `maxResults` (type: `integer`):

Maximum number of ads to scrape (API returns 100 per page, actor handles pagination)

## Actor input object example

```json
{
  "searchQuery": "running shoes",
  "country": "US",
  "adType": "all",
  "adStatus": "active",
  "maxResults": 100
}
```

# 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 = {
    "searchQuery": "running shoes"
};

// Run the Actor and wait for it to finish
const run = await client.actor("aurumworks/facebook-ads-library").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 = { "searchQuery": "running shoes" }

# Run the Actor and wait for it to finish
run = client.actor("aurumworks/facebook-ads-library").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 '{
  "searchQuery": "running shoes"
}' |
apify call aurumworks/facebook-ads-library --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Facebook Ads Library Scraper — Meta Ad Library API",
        "description": "Extract ads from the Meta Ad Library using the official Graph API. Search by keyword or advertiser, filter by country and status. Get ad creatives, copy, spend ranges, impressions, demographics, and platform data. Auto-pagination, flat output schema, CSV/Excel export.",
        "version": "0.1",
        "x-build-id": "8rNawdnmYXGNTQm7I"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/aurumworks~facebook-ads-library/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-aurumworks-facebook-ads-library",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/aurumworks~facebook-ads-library/runs": {
            "post": {
                "operationId": "runs-sync-aurumworks-facebook-ads-library",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/aurumworks~facebook-ads-library/run-sync": {
            "post": {
                "operationId": "run-sync-aurumworks-facebook-ads-library",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "accessToken": {
                        "title": "Meta Access Token",
                        "type": "string",
                        "description": "Meta Graph API access token with ads_read permission. Get one at https://developers.facebook.com/tools/explorer/"
                    },
                    "searchQuery": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Keywords to search for in ads (e.g. 'running shoes', 'SaaS')"
                    },
                    "pageId": {
                        "title": "Page ID",
                        "type": "string",
                        "description": "Facebook Page ID to get all ads from a specific advertiser"
                    },
                    "country": {
                        "title": "Country Code",
                        "type": "string",
                        "description": "Two-letter country code (e.g. US, GB, IN, AE, DE)",
                        "default": "US"
                    },
                    "adType": {
                        "title": "Ad Type",
                        "enum": [
                            "all",
                            "political_and_issue_ads"
                        ],
                        "type": "string",
                        "description": "Type of ads to search",
                        "default": "all"
                    },
                    "adStatus": {
                        "title": "Ad Status",
                        "enum": [
                            "active",
                            "inactive",
                            "all"
                        ],
                        "type": "string",
                        "description": "Filter by ad status",
                        "default": "active"
                    },
                    "maxResults": {
                        "title": "Max Results",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Maximum number of ads to scrape (API returns 100 per page, actor handles pagination)",
                        "default": 100
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```