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

Facebook Ads Scraper is a powerful Apify Actor that tracks competitor advertisements across Facebook and Instagram using the Meta Ads Library. This Actor extracts ad creatives, copy, CTAs, offers, and longevity signals, giving you comprehensive insights into what your competitors are advertising.

- **URL**: https://apify.com/happitap/facebook-ads-scraper.md
- **Developed by:** [HappiTap](https://apify.com/happitap) (community)
- **Categories:** Social media, Lead generation, Other
- **Stats:** 83 total users, 7 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 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 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

**Monitor and extract Facebook and Instagram ads from the Meta Ads Library.**

**Facebook Ads Scraper** is a powerful Apify Actor that tracks competitor advertisements across **Facebook** and **Instagram** using the Meta Ads Library. This Actor extracts ad creatives, copy, CTAs, offers, and longevity signals, giving you comprehensive insights into what your competitors are advertising.

Simply provide brand names, keywords, or domains, and the Actor will search the Meta Ads Library to find matching ads. The Actor automatically extracts and normalizes offer information, detects marketing angles, and calculates longevity scores to help you identify winning creatives.

Visit the [Meta Ads Library](https://www.facebook.com/ads/library) to see the data source this Actor monitors.

### Why use Facebook Ads Scraper?

#### Business Use Cases

- **Performance Marketers**: Track competitor ad launches, identify successful offers, and discover new creative angles on Facebook and Instagram
- **Agencies**: Monitor client competitors, track domain-based campaigns, and generate competitive intelligence reports
- **DTC Founders**: Research offers and angles in your category, identify long-running successful creatives, and detect ad fatigue signals
- **Growth Teams**: Monitor competitor strategies, analyze CTA patterns, and benchmark creative performance

#### Platform Advantages

This Actor leverages the **Apify platform** to provide:

- **Automated Monitoring**: Schedule runs to track competitors continuously
- **API Access**: Integrate competitor data into your workflows via REST API
- **Proxy Rotation**: Built-in residential proxy support to avoid blocks from Meta
- **Scalable Infrastructure**: Handle large-scale monitoring without infrastructure management
- **Data Export**: Download results in JSON, CSV, Excel, or HTML formats
- **Webhook Integration**: Get notified when new ads are detected
- **Integration Ready**: Connect to Zapier, Make, or custom workflows

### What can Facebook Ads Scraper extract?

The Actor extracts comprehensive data from the Meta Ads Library:

| Data Field | Description | Example |
|------------|-------------|---------|
| **Ad Creative** | Image or video URL | `https://...` |
| **Ad Copy** | Full text of the advertisement | "Get 20% off today!" |
| **Headline** | Ad headline text | "Special Sale" |
| **CTA** | Call-to-action (normalized) | `shop_now`, `learn_more` |
| **Landing Page** | Destination URL | `https://brand.com/sale` |
| **Advertiser** | Brand/advertiser name | "Nike" |
| **Offer Type** | Detected offer classification | `discount_percent`, `free_shipping` |
| **Offer Details** | Structured offer data | `{percentOff: 20}` |
| **Longevity Score** | Days active score (0-100) | 85 |
| **Marketing Angles** | Detected angles | `["scarcity", "urgency"]` |
| **Geo Targets** | Targeted countries | `["US", "GB"]` |
| **Status** | Ad status | `active`, `inactive` |
| **First/Last Seen** | Monitoring timestamps | `2024-01-15T10:00:00Z` |

### How to scrape Facebook ads

#### Step-by-Step Tutorial

1. **Sign up for Apify** (if you haven't already) - Create a free account at [apify.com](https://apify.com)

2. **Open the Actor** - Navigate to the Facebook Ads Scraper Actor page

3. **Configure Input** - Click on the **Input** tab and set:
   - **Search Mode**: Choose advertiser, keyword, or domain mode
   - **Queries**: Enter brand names (e.g., "Nike"), keywords, or domains to search
   - **Geographic Targets**: Select country codes (e.g., US, GB)

4. **Run the Actor** - Click "Start" to begin monitoring

5. **View Results** - Once complete, check the **Output** tab for:
   - Overview of all ads
   - New ads detected
   - Offers and CTAs analysis
   - Longevity analysis

6. **Export Data** - Download results in your preferred format (JSON, CSV, Excel)

### How much does it cost?

This Actor uses a **Pay-Per-Event (PPE)** pricing model. You are charged based on the number of ads successfully scraped and extracted.

**Cost**: $1.50 per 1,000 ads scraped (example pricing - check Actor page for current rates)

This model offers several advantages:

- **Predictable Costs**: You only pay for the data you receive.
- **No Surprises**: Failed requests or retries do not incur additional costs.
- **Control**: Use the `maxResultsPerQuery` input to set a hard limit on your spend.

#### Pricing Estimates

- **100 Ads**: ~$0.15
- **1,000 Ads**: ~$1.50
- **10,000 Ads**: ~$15.00

**Note**: Monthly platform subscription fees and proxy usage fees may still apply depending on your Apify plan. Residential proxies (recommended for Meta) are highly cost-effective with this specific Actor architecture.

### Features

#### Smart Data Collection

- **Meta Ads Library API & Scraping**: Uses a hybrid approach (official API + scraping) for maximum reliability
- **Automatic Retries**: Handles network errors and temporary blocks
- **Proxy Support**: Essential for avoiding rate limits and blocks from Facebook
- **Incremental State Tracking**: Remembers ads from previous runs to identify new ones

#### Intelligence Features

- **Offer Extraction**: Automatically detects discounts, free shipping, trials, etc.
- **Longevity Scoring**: Calculates how long ads have been running to identify winners
- **CTA Normalization**: Standardizes call-to-action button text

### Input Options

#### Required Fields

- **Search Mode**: Choose `advertiser`, `keyword`, or `domain` mode
- **Queries**: Enter brand names, keywords, or domains to search

#### Recommended Settings

- **Max Results Per Query**: 100-200 for most use cases
- **Geographic Targets**: Country codes (e.g., `["US"]`, `["US", "GB"]`)
- **Date Range**: 30 days for recent monitoring, 60-90 for broader research
- **Use Apify Proxy**: Enable for production use (highly recommended)
- **Slow Mode**: Enable to avoid blocks

### Output

You can download the dataset extracted by Facebook Ads Scraper in various formats such as **JSON**, **HTML**, **CSV**, or **Excel**.

#### Output Example

```json
{
  "platform": "meta",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=Nike",
  "adId": "123456789",
  "advertiserName": "Nike",
  "advertiserId": "789012345",
  "geoTargets": ["US"],
  "language": "en",
  "adCopy": "Just Do It. Get 20% off select styles. Limited time offer. Shop now!",
  "headline": "Nike Sale - 20% Off",
  "ctaRaw": "Shop Now",
  "ctaNormalized": "shop_now",
  "landingPageUrl": "https://www.nike.com/sale",
  "creativeType": "image",
  "creativeUrls": ["https://static.nike.com/a/images/..."],
  "thumbnailUrl": "https://static.nike.com/a/images/...",
  "firstSeenAt": "2024-01-15T10:00:00Z",
  "lastSeenAt": "2024-01-20T10:00:00Z",
  "platformStartDate": "2024-01-10",
  "platformEndDate": null,
  "status": "active",
  "offerType": "discount_percent",
  "offerDetails": {
    "percentOff": 20
  },
  "offerParseConfidence": 0.8,
  "angleTags": ["scarcity", "urgency"],
  "angleConfidence": 0.7,
  "daysActive": 5,
  "longevityScore": 20,
  "fingerprint": "meta:123456789",
  "runId": "abc123xyz",
  "scrapedAt": "2024-01-20T10:00:00Z",
  "dataQuality": "full",
  "isNew": true,
  "notes": ""
}
```

### Is it legal to scrape Facebook ads?

Our Actor is ethical and only accesses **public ad transparency data** provided by Meta. The Meta Ads Library is specifically designed to provide transparency into advertising, and we do not extract any private user data.

The Actor:

- ✅ Only accesses publicly available ad library data
- ✅ Does not require login credentials
- ✅ Does not bypass authentication
- ✅ Respects platform rate limits

However, you should be aware that:

- Ad library data may contain public information about advertisers
- You should comply with Meta's terms of service
- Use the data ethically and in compliance with applicable laws

### FAQ

#### What if I get blocked?

Meta has strict anti-scraping measures. If you encounter blocks:

1. Enable residential proxies (`useApifyProxy: true`, `proxyGroups: ["RESIDENTIAL"]`)
2. Enable slow mode (`slowMode: true`)
3. Reduce concurrency (`maxConcurrency: 1-2`)
4. Increase retries (`maxRetries: 5`)

#### Can I monitor ads in multiple countries?

Yes! Use the `geo` parameter to specify multiple country codes. Example: `["US", "GB", "CA", "AU"]`

### Support

- **Issues Tab**: Report bugs or request features
- **Apify Support**: Contact Apify support for platform issues

# Actor input Schema

## `platforms` (type: `array`):

Platform to monitor. Default is Meta (Facebook/Instagram).

## `mode` (type: `string`):

Choose how to search for ads:

- **Brand/Advertiser Monitor**: Search by brand names, advertiser IDs, or page names. Best for tracking specific competitors.
- **Keyword Monitor**: Search by keywords that appear in ad copy, landing pages, or advertiser names. Best for category research.
- **Domain/Landing Page Monitor**: Search by domain names (e.g., brand.com). Best for agencies tracking client competitors.

## `queries` (type: `array`):

Enter your search queries. The meaning depends on the selected mode:

- **Advertiser mode**: Brand names, advertiser names, or page names (e.g., "Nike", "Adidas")
- **Keyword mode**: Keywords to search for in ad copy (e.g., "skincare", "anti-aging")
- **Domain mode**: Domain names without protocol (e.g., "example.com", "brand.com")

You can enter multiple queries.

## `maxResultsPerQuery` (type: `integer`):

Maximum number of ads to fetch per query. Higher values may take longer to process.

- **Recommended**: 100-200 for most use cases. Increase to 500-1000 for comprehensive monitoring.

## `geo` (type: `array`):

Country codes (ISO 3166-1 alpha-2) where ads are targeted. Examples: US, GB, IN, CA, AU.

Enter multiple country codes to search across regions.

## `dateRangeDays` (type: `integer`):

How far back to search for ads in days. The actor will look for ads that were active within this time period.

- **Recommended**: 30 days for recent monitoring, 60-90 days for broader research.

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

Filter ads by their current status:

- **Active Only**: Only ads currently running
- **Inactive Only**: Only ads that have stopped running
- **All**: Both active and inactive ads

## `languages` (type: `array`):

Language codes (ISO 639-1) to filter ads. Examples: en, es, fr, de. Leave empty to search all languages.

This is optional and may not be supported by all platforms.

## `useApifyProxy` (type: `boolean`):

Enable proxy rotation to avoid IP blocks. **Highly recommended** for production use.

When enabled, the actor will use Apify's proxy service to rotate IP addresses. This helps prevent blocks from ad transparency libraries.

## `proxyGroups` (type: `array`):

Proxy groups to use. Available options:

- **RESIDENTIAL**: Residential IP addresses (recommended, slower but more reliable)

- **DATACENTER**: Datacenter IP addresses (faster but may be blocked more often)

- **SHADER**: Shader proxy group

- **Recommended**: Use RESIDENTIAL for best results, especially for Meta.

## `proxyCountry` (type: `string`):

Country code for proxy IP addresses. Using proxies from the same country as your target geo can improve success rates.

- **US**: United States (default, best for Meta)
- **GB**: United Kingdom
- **DE**: Germany

## `maxConcurrency` (type: `integer`):

Maximum number of concurrent requests. Lower values are safer but slower.

- **Recommended**: 3 for most cases. Reduce to 1-2 if you encounter blocks. Increase to 5-10 only if you have reliable proxies.

## `slowMode` (type: `boolean`):

Add random delays (1-3 seconds) between requests to avoid blocks. **Highly recommended** for production use.

When enabled, the actor will wait between requests, making it slower but significantly reducing the chance of being blocked.

## `maxRetries` (type: `integer`):

Maximum number of retry attempts for failed requests. The actor will automatically retry on network errors, timeouts, and temporary blocks.

## `extractOffers` (type: `boolean`):

Enable automatic offer extraction and normalization. The actor will:

- Detect offer types (discount\_percent, flat\_off, bogo, free\_shipping, bundle, free\_trial, etc.)
- Extract structured offer details (percent off, amounts, trial days)
- Normalize CTAs (shop\_now, learn\_more, sign\_up, etc.)
- Detect marketing angles (social proof, scarcity, urgency, etc.)

Each extraction includes a confidence score (0-1).

## `downloadCreatives` (type: `boolean`):

Download creative assets (images/videos) to Apify Key-Value Store. **Note**: This increases storage usage and processing time.

When enabled, all creative assets will be downloaded and stored in the Key-Value store for later access.

## `computeLongevity` (type: `boolean`):

Calculate ad longevity scores based on how long ads have been running. Long-running ads often indicate successful creatives.

Scoring:

- 0-7 days: Score 20
- 8-21 days: Score 50
- 22-60 days: Score 80
- 60+ days: Score 100

## `onlyNewSinceLastRun` (type: `boolean`):

Only return ads that were seen for the first time in this run. Useful for monitoring workflows where you only want to be notified of new ads.

- **Note**: This requires state from previous runs. On the first run, all ads will be marked as new.

## Actor input object example

```json
{
  "platforms": [
    "meta"
  ],
  "mode": "advertiser",
  "queries": [
    "Nike"
  ],
  "maxResultsPerQuery": 200,
  "geo": [
    "US"
  ],
  "dateRangeDays": 30,
  "adStatus": "all",
  "languages": [],
  "useApifyProxy": true,
  "proxyGroups": [
    "RESIDENTIAL"
  ],
  "proxyCountry": "US",
  "maxConcurrency": 3,
  "slowMode": true,
  "maxRetries": 3,
  "extractOffers": true,
  "downloadCreatives": false,
  "computeLongevity": true,
  "onlyNewSinceLastRun": false
}
```

# 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 = {
    "queries": [
        "Nike"
    ]
};

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

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

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ab5lYUuxIkThybgp1/builds/QxUrqAuKwnTSdICJn/openapi.json