# Facebook Ads Scraper (`techbellys/facebook-ads-scraper`) Actor

Scrape ads from the Meta (Facebook) Ad Library via the internal GraphQL endpoint.

- **URL**: https://apify.com/techbellys/facebook-ads-scraper.md
- **Developed by:** [Prabhat pankaj](https://apify.com/techbellys) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$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/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 Scraper

Scrape ads from the Meta (Facebook) Ad Library. Accepts Facebook Page URLs or
Meta Ad Library search URLs (with filters) and returns structured ad data.

### How it works

Instead of scraping rendered HTML, this Actor queries the Ad Library internal
GraphQL endpoint (`AdLibrarySearchPaginationQuery`) directly and paginates
through results using the connection cursor. This is faster and returns the
full structured `snapshot` for each ad.

### Input

- `startUrls` – one or more Facebook Page URLs or Meta Ad Library URLs.
- `resultsLimit` – max ads per URL (empty = as many as possible).
- `activeStatus` – `active`, `inactive`, or both (used if not in the URL).
- `sorting` – default / impressions / relevance (used if not in the URL).
- `isDetailsPerAd` – include per-ad detail (reach, spend, Instagram data).
- `includeAboutPage` – include page About / transparency data.
- `onlyTotal` – return only the total ad count per page.
- `onlyAdsNewerThan` / `onlyAdsOlderThan` – date filters on ad start date.

### Output

Each dataset item is one ad, including `pageId`, `adArchiveId`, `isActive`,
`publisherPlatform`, `startDateFormatted` / `endDateFormatted`, `spend`,
`reachEstimate`, and a nested `snapshot` object with the creative (title,
body, cards, images, videos, CTA, link).

### Notes

Facebook aggressively rate-limits and blocks datacenter IPs. Residential
proxies are strongly recommended (configured by default).

# Actor input Schema

## `keywords` (type: `array`):

Plain search terms, e.g. "online mba course". The full Meta Ad Library URL is generated automatically from these plus the country / sorting / media type fields below. Use this instead of Start URLs when your backend only has a keyword.

## `keyword` (type: `string`):

Convenience alias for a single keyword. Merged with Search keywords.

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

Two-letter country code used when building the Ad Library URL from keywords.

## `searchType` (type: `string`):

How the keyword is matched. Exact phrase automatically wraps the keyword in quotes.

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

Maps to ad\_type in the Ad Library URL. Leave as All ads for normal commercial ads.

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

Maps to media\_type in the Ad Library URL, e.g. Video to only collect video creatives.

## `isTargetedCountry` (type: `boolean`):

Maps to is\_targeted\_country in the Ad Library URL.

## `sortDirection` (type: `string`):

Maps to sort\_data\[direction] in the Ad Library URL.

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

Add a Facebook Page URL, a brand URL from Meta Ad Library, or a Meta Ad Library search URL. You can add multiple URLs using the Bulk edit option.

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

Maximum ads to scrape per input URL. Leave empty to scrape as many as possible.

## `activeStatus` (type: `string`):

Filter ads by whether they are currently running.

## `sorting` (type: `string`):

Sort order for scraped ads.

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

Adds an ad\_details object with advertiser page info.

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

Extracts About tab details (business address, admin locations, page history).

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

Returns only the total number of ads per page instead of scraping individual ads.

## `onlyAdsNewerThan` (type: `string`):

Only scrape ads with a start date newer than this date (e.g. 2025-01-01).

## `onlyAdsOlderThan` (type: `string`):

Only scrape ads with a start date older than this date (e.g. 2025-01-01).

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

Residential proxies are strongly recommended; Facebook blocks datacenter IPs.

## Actor input object example

```json
{
  "keywords": [
    "online mba course"
  ],
  "keyword": "",
  "country": "IN",
  "searchType": "keyword_unordered",
  "adType": "all",
  "mediaType": "all",
  "isTargetedCountry": false,
  "sortDirection": "desc",
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered"
    }
  ],
  "resultsLimit": 10,
  "activeStatus": "",
  "sorting": "",
  "isDetailsPerAd": false,
  "includeAboutPage": false,
  "onlyTotal": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "keywords": [
        "online mba course"
    ],
    "startUrls": [
        {
            "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("techbellys/facebook-ads-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 = {
    "keywords": ["online mba course"],
    "startUrls": [{ "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered" }],
}

# Run the Actor and wait for it to finish
run = client.actor("techbellys/facebook-ads-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 '{
  "keywords": [
    "online mba course"
  ],
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_unordered"
    }
  ]
}' |
apify call techbellys/facebook-ads-scraper --silent --output-dataset

```

## MCP server setup

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