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

Search public Facebook Ads Library records by keyword or advertiser, export structured ad and creative data, and optionally retrieve bounded ad details.

- **URL**: https://apify.com/data-slayer/facebook-ads-library-scraper.md
- **Developed by:** [Data Slayer](https://apify.com/data-slayer) (community)
- **Categories:** Marketing, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 ad results

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 Ads Library Scraper

Search public Facebook Ads Library records by keyword or advertiser, export structured ad and creative data, and optionally add bounded ad details for competitive research.

### Watch the demo

YouTube video coming soon.

### What this Actor does

Search ads by keyword, resolve advertiser pages, collect ads for known public page IDs, or retrieve details for known ad IDs. The Actor enforces independent row, page, and detail caps and exports separate `ad`, `advertiser`, `creative`, and `ad_detail` records.

### Input

Use `searchTerms`, `advertiserQueries`, `advertiserPageIds`, or `adIds`. Control scope with `country`, `adStatus`, `mediaType`, `maxItems`, `maxPages`, `includeDetails`, and `maxDetailItems`. Direct `adIds` require `includeDetails=true`.

```json
{
  "searchTerms": ["running shoes"],
  "country": "US",
  "adStatus": "active",
  "mediaType": "video",
  "maxItems": 100,
  "maxPages": 10,
  "includeDetails": true,
  "maxDetailItems": 20
}
```

### Output

- `ad`: one unique ad discovery result.
- `advertiser`: one advertiser-page discovery result.
- `creative`: creative copy and public asset links included with a parent result; not billed separately.
- `ad_detail`: one separately priced successful detail result.

Run completion and billing reconciliation counts are stored in `OUTPUT` and `RUN_SUMMARY`, outside the default dataset.

### Limits

Only public data is processed. Spend and impression ranges remain `null` when they are not exposed for the selected ad category or region. Transcripts and cross-run monitoring are not part of this version. Creative links can expire. Empty, partial, failed, rate-limited, and billing-uncertain outcomes are reported explicitly.

Use public data responsibly and follow the platform terms and laws that apply to your use case.

### FAQ

**How much does it cost to run this Actor?**
Pricing is listed in the Pricing section above, charged per row returned. You only pay for the rows
the Actor actually produces, so a small test run costs cents.

**Do I need cookies or a login?**
No. This Actor reads public data only - no cookies, no account, no browser automation.

**Can I schedule it?**
Yes. Run it from the Apify API, on a schedule, or via a webhook, and export results as JSON, CSV or Excel.

**What if I need a slightly different output?**
Open an issue on the Actor's Issues tab describing the shape you need.

### Related actors

More Facebook actors from the same portfolio. Apify only auto-recommends actors in the same category, so here are the rest of ours:

| Actor |
|---|
| [Facebook Comments & Replies Scraper](https://apify.com/data-slayer/facebook-comments-scraper) |
| [Facebook Events Scraper · No Cookies](https://apify.com/data-slayer/facebook-search-events) |
| [Facebook Group Posts Scraper · No Cookies](https://apify.com/data-slayer/facebook-group-posts) |
| [Facebook Keyword Post Search · Public Posts](https://apify.com/data-slayer/facebook-post-search) |
| [Facebook Marketplace Listing Scraper · No Cookies](https://apify.com/data-slayer/facebook-marketplace-details) |
| [Facebook Page Details Scraper · No Cookies](https://apify.com/data-slayer/facebook-page-details) |
| [Facebook Page Posts Scraper · No Cookies](https://apify.com/data-slayer/facebook-page-posts) |
| [Facebook Page Reviews Scraper · No Cookies](https://apify.com/data-slayer/facebook-page-reviews) |
| [Facebook Page Search Scraper · No Cookies](https://apify.com/data-slayer/facebook-search-pages) |
| [Facebook People Search Scraper · No Cookies](https://apify.com/data-slayer/facebook-search-people) |
| [Facebook Public Profile Scraper · People Lookup by URL or ID](https://apify.com/data-slayer/facebook-profile-scraper) |

# Actor input Schema

## `searchTerms` (type: `array`):

Keywords, brands, products, or topics to search in the public Ads Library.

## `advertiserQueries` (type: `array`):

Optional advertiser names to resolve before collecting ads.

## `advertiserPageIds` (type: `array`):

Optional numeric public page IDs whose ads you want to collect.

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

Optional numeric Ads Library IDs to retrieve directly. Enable ad details when using this field.

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

Use a two-letter ISO country code or ALL. Coverage depends on what the public Ads Library exposes for the selected ad category and region.

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

Return active ads, inactive ads, or both when supported.

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

Limit results to image or video ads when supported.

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

Hard cap across ad and advertiser discovery rows. Detail and included creative records are counted separately.

## `maxPages` (type: `integer`):

Safety cap for pagination on each keyword, advertiser query, or page ID.

## `includeDetails` (type: `boolean`):

Retrieve a separate ad-detail record for accepted ads, up to the detail cap. This creates a separate billable event per successful detail record.

## `maxDetailItems` (type: `integer`):

Hard cap for separately priced ad-detail records when details are enabled.

## Actor input object example

```json
{
  "searchTerms": [
    "running shoes"
  ],
  "country": "US",
  "adStatus": "active",
  "mediaType": "all",
  "maxItems": 100,
  "maxPages": 10,
  "includeDetails": false,
  "maxDetailItems": 25
}
```

# Actor output Schema

## `dataset` (type: `string`):

Ad, advertiser, creative, and ad-detail records. Creative records are included with their parent result and are not a separate billable event.

## `summary` (type: `string`):

Completion, request, output, retry, partial-result, and billing reconciliation counts.

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

// Run the Actor and wait for it to finish
const run = await client.actor("data-slayer/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 = { "searchTerms": ["running shoes"] }

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

```

## MCP server setup

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