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

Extract advertising data from Facebook, Instagram, WhatsApp, Threads. Get ads, publishers, prices, reach estimates, impressions, links, images, IDs, timestamps, product info, and more from Facebook Ad Library. Export ad data, schedule runs via API, and integrate with other tools or AI workflows.

- **URL**: https://apify.com/dewy\_settee/facebook-ads-library-scraper.md
- **Developed by:** [Tha Thu](https://apify.com/dewy_settee) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 ads

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

### 🚀 What does Facebook Ads Scraper API Wrapper do?

**Facebook Ads Scraper API Wrapper** is an intermediary Actor for collecting publicly available ad data from the [Facebook Ads Library](https://www.facebook.com/ads/library/) and Facebook pages through the [Facebook Ads Scraper](https://apify.com/apify/facebook-ads-scraper) Actor. It receives a list of URLs, runs the source scraper, and saves the processed records to the **default dataset of the current run**.

This design is ideal when your application needs one stable endpoint and dataset. Apify handles cloud execution, run monitoring, scheduling, webhooks, integrations, and data exports. The token used to call the source scraper stays in the Actor's secure environment and is never returned to the client.

### ✨ Why use Facebook Ads Scraper API Wrapper?

This Actor is useful for marketing teams, market researchers, agencies, and developers building automated advertising-data workflows. Use it to monitor competitors, research creatives and messaging, identify industry trends, or feed data into a CRM, warehouse, or internal dashboard.

The wrapper also gives you a convenient control layer for normalizing field names, filtering records, validating data, or adding enrichment later. Clients do not need to change when you update the logic in `transformFacebookAds()`.

### 🧭 How to scrape Facebook ads with Apify

1. Open the Actor in the Apify Console and go to the **Input** tab.
2. Configure `APIFY_TOKEN` in the Actor environment. The token must be allowed to run `apify/facebook-ads-scraper`.
3. Add one or more Facebook page URLs or Facebook Ads Library search URLs.
4. Select a result limit and the detail options you need, then click **Start**.
5. Once the run is `SUCCEEDED`, open **Storage > Dataset** to view or export the results.

When integrating through the API, save the wrapper run ID and check its status before reading the dataset. You can also create an `ACTOR.RUN.SUCCEEDED` webhook so your system receives the results as soon as the run finishes.

### ⚙️ Input: Facebook page or Ads Library URLs

The main fields available in the **Input** tab are:

| Field                     | Description                                                                 |
| ------------------------- | --------------------------------------------------------------------------- |
| `startUrls`               | Required. A list of Facebook page URLs or Facebook Ads Library search URLs. |
| `resultsLimit`            | Maximum number of ads to collect. Default: `10`.                            |
| `enrichWithEcommerceData` | Enrich ads with e-commerce data when supported by the source scraper.       |
| `includeAboutPage`        | Include public information from the Facebook page's About section.          |
| `isDetailsPerAd`          | Request detailed information for every ad.                                  |
| `onlyTotal`               | Return aggregate totals instead of individual ads.                          |

Example input:

```json
{
    "resultsLimit": 20,
    "enrichWithEcommerceData": false,
    "includeAboutPage": false,
    "isDetailsPerAd": false,
    "onlyTotal": false,
    "startUrls": [
        { "url": "https://www.facebook.com/SHEINOFFICIAL" },
        {
            "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&search_type=page&view_all_page_id=15087023444"
        }
    ]
}
```

Every URL must be a valid Facebook page or a search URL generated by Facebook Ads Library. Start with a small result limit to validate your query before scaling up.

### 📦 Output: ad data in your Dataset

After the source scraper completes successfully, this wrapper preserves the returned records and writes them to the run's default dataset. The exact fields depend on your query and the data available through Facebook Ads Library; they commonly include advertiser details, ad text, media, delivery information, and source URLs.

A simplified output record might look like this:

```json
{
    "pageName": "Example Brand",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=...",
    "adText": "Discover our latest offer.",
    "startDate": "2026-08-01",
    "mediaType": "IMAGE"
}
```

You can download the dataset in formats such as **JSON, HTML, CSV, or Excel**, or access it through the Apify Dataset API for use in your own workflow. Fields can change when the source Actor changes; if you need your own schema, update `transformFacebookAds()` before records are written to the dataset.

### 📊 Main data fields

| Data group | Possible contents                                           |
| ---------- | ----------------------------------------------------------- |
| Advertiser | Page name, page ID, and other related public information.   |
| Ad content | Text, headline, call to action, and creative content.       |
| Media      | Media type, image or video, and media links when available. |
| Delivery   | Start date, active status, and delivery platforms.          |
| Source     | Facebook Ads Library URL for referencing the record.        |

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

The primary cost is the **Facebook Ads Scraper** run. It depends on that Actor's pricing model, the number of URLs, the number of ads collected, and options such as enrichment or per-ad details. This wrapper also uses compute while calling the scraper and copying records to its own dataset.

To control cost, start with one URL and a low `resultsLimit`, review usage in the Apify Console, and then scale up. Your Apify account may have plan-specific limits or allowances.

### 💡 Tips and advanced options

- Use Ads Library URLs already filtered by country, status, platform, or page for more precise results.
- Save the run ID and use a webhook instead of keeping an HTTP connection open until the task finishes.
- Enable `isDetailsPerAd`, `includeAboutPage`, or enrichment only when needed, as they can make the run take longer.
- Never put `APIFY_TOKEN` in source code, Actor input, or client-side tools. Store it only in environment variables or Apify Secrets.
- Schedule recurring runs to build a creative history and monitor competitor changes over time.

### 🛡️ FAQ, compliance, and support

#### 🔎 Can this Actor scrape ads from any page?

The Actor works with public ad data that Facebook Ads Library and the source scraper can access. Availability, returned fields, and completeness can change based on Facebook, your query, and the source Actor.

#### 🔢 Can I retrieve only the total number of ads?

Yes. Enable `onlyTotal` in the Input tab. The returned record format depends on how Facebook Ads Scraper represents aggregate values.

#### 🧩 Can I customize the output data?

Yes. The project intentionally preserves the source schema. Developers can add filtering, rename fields, or enrich records in the `transformFacebookAds()` function in `src/scrape.js`.

You are responsible for ensuring that your use of the data complies with applicable laws, Facebook's terms, and privacy requirements. Do not use this Actor to collect or store sensitive personal data without an appropriate legal basis. For support or a tailored workflow, submit a request through the Actor's **Issues** tab.

# Actor input Schema

## `enrichWithEcommerceData` (type: `boolean`):

Whether to enrich ads with e-commerce data.

## `includeAboutPage` (type: `boolean`):

Whether to include data from a Facebook page About section.

## `isDetailsPerAd` (type: `boolean`):

Whether to request detailed information for each ad.

## `onlyTotal` (type: `boolean`):

Whether to return only aggregate totals instead of ads.

## `resultsLimit` (type: `integer`):

Maximum number of ads to collect.

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

Facebook page URLs or Facebook Ads Library search URLs.

## Actor input object example

```json
{
  "enrichWithEcommerceData": false,
  "includeAboutPage": false,
  "isDetailsPerAd": false,
  "onlyTotal": false,
  "resultsLimit": 10,
  "startUrls": [
    {
      "url": "https://www.facebook.com/SHEINOFFICIAL"
    }
  ]
}
```

# Actor output Schema

## `dataset` (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 = {
    "startUrls": [
        {
            "url": "https://www.facebook.com/SHEINOFFICIAL"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("dewy_settee/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 = { "startUrls": [{ "url": "https://www.facebook.com/SHEINOFFICIAL" }] }

# Run the Actor and wait for it to finish
run = client.actor("dewy_settee/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 '{
  "startUrls": [
    {
      "url": "https://www.facebook.com/SHEINOFFICIAL"
    }
  ]
}' |
apify call dewy_settee/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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