# Facebook Ad Library Scraper - Active Ads & Creatives (`thirdwatch/fb-ad-library-scraper`) Actor

Scrape Facebook's public Ad Library for any brand. Returns active ad count, per-creative text, CTA, start date, and platform mix (Facebook, Instagram, Messenger, Audience Network).

- **URL**: https://apify.com/thirdwatch/fb-ad-library-scraper.md
- **Developed by:** [Thirdwatch](https://apify.com/thirdwatch) (community)
- **Categories:** Social media, SEO tools
- **Features:** Limited permissions
- **Stats:** 29 total users, 3 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $22.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.
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 Ad Library Scraper

> **Thirdwatch portfolio:** 8,800+ users across 140+ public Actors, 2M+ records delivered, >95% run success. [Explore all Thirdwatch Actors](https://apify.com/thirdwatch).

Scrape public Meta Ad Library results for brands, keywords, and ad categories. Use it to monitor active ads, collect creative text snippets, track CTAs, compare platform mix, and build competitor ad swipe files across Facebook, Instagram, Messenger, and Audience Network where Meta exposes the data.

### Value prop

Meta's Ad Library is one of the most accessible public sources for seeing which ads are currently active for a brand or keyword. This actor packages that public Ad Library view into Apify dataset rows so growth teams, agencies, researchers, and compliance teams can monitor ad activity without manually searching the Library one brand at a time.

Best fit:

- Growth teams tracking competitor creative angles and CTAs.
- Agencies building swipe files and pitch research.
- Brand teams auditing their own active ad inventory.
- Researchers monitoring political, issue, housing, employment, or credit ads.
- Compliance teams checking regulated ad categories.

### What's new

- Full ad details per creative: ad body text, headline, destination link, CTA, ad format, page name and page link.
- Image and video URLs for each captured ad.
- Start and stop dates (human-readable and ISO), active/inactive status and the Ad Library link for every ad.
- New filters: ad status (active, inactive, or both) and media type (image, video, meme, or none).
- Faster runs: most brands finish in a few seconds.

### What data you get

One dataset item per brand or keyword:

| Field | Description |
|-------|-------------|
| `brand` | Brand or keyword searched |
| `country` | Country filter applied, or `ALL` |
| `adType` | Ad category requested |
| `activeStatus` | Ad status filter applied (`all`, `active`, `inactive`) |
| `mediaType` | Media type filter applied |
| `url` | Meta Ad Library search URL |
| `active` | `true` when the search matched at least one ad |
| `adCount` | Number of matching ads reported by the Ad Library (capped at 50,000) |
| `adCountIsLowerBound` | `true` when the Ad Library reports "more than 50,000" |
| `creatives` | Array of captured ads (see below) |
| `creativeCount` | Number of ads captured |
| `scrapedAt` | Scrape timestamp (UTC) |

#### Creative fields

| Field | Description |
|-------|-------------|
| `library_id` | Ad Library ID |
| `ad_url` | Direct link to the ad in the Ad Library |
| `is_active` | Whether the ad is currently running |
| `startDate` / `start_date_iso` | Date the ad started running |
| `endDate` / `end_date_iso` | Date the ad stopped running (empty for active ads) |
| `platforms` | Facebook, Instagram, Messenger, Audience Network, Threads, WhatsApp |
| `page_name`, `page_id`, `page_url`, `page_like_count`, `page_categories` | Advertiser page details |
| `body` | Ad body text |
| `title` | Ad headline |
| `caption` | Display domain shown under the ad |
| `link_url` | Destination link |
| `cta`, `cta_type` | Call-to-action button text and type |
| `display_format` | Ad format, e.g. `IMAGE`, `VIDEO`, `CAROUSEL`, `DCO`, `DPA` |
| `image_url`, `image_urls`, `video_url` | Creative media URLs |
| `variants_count` | Number of cards/variants in the ad |
| `textSnippet` | Page name, body, headline and CTA combined |
| `spend`, `currency`, `reach_estimate` | Disclosure fields, when Meta publishes them (mostly political and issue ads) |

### Quick-start input examples

#### Track active ads for brands worldwide

```json
{
  "brands": ["allbirds", "hoka", "on running"],
  "country": "ALL",
  "adType": "all",
  "maxCreatives": 20
}
```

#### Check one country

```json
{
  "brands": ["nykaa", "myntra"],
  "country": "IN",
  "adType": "all",
  "maxCreatives": 50
}
```

#### Political or issue ad monitoring

```json
{
  "brands": ["climate policy", "election campaign"],
  "country": "US",
  "adType": "political_and_issue_ads",
  "maxCreatives": 100
}
```

#### Count-only monitoring

```json
{
  "brands": ["example brand"],
  "country": "ALL",
  "adType": "all",
  "maxCreatives": 0
}
```

### Input parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `brands` | Yes | Brand names or pages to search in the Facebook Ad Library. Each brand returns one dataset item with the active ad count, country, and up to `maxCreatives` creative samples. |
| `country` | No | ISO country code (e.g. `US`, `IN`, `GB`, `CA`, `AU`) or `ALL` for worldwide. Default `ALL`. |
| `adType` | No | Ad category to search: `all` (default), `political_and_issue_ads`, `housing_ads`, `employment_ads`, or `credit_ads`. |
| `adActiveStatus` | No | `all` (default), `active`, or `inactive`. |
| `mediaType` | No | `all` (default), `image`, `video`, `meme`, `image_and_meme`, or `none`. |
| `maxCreatives` | No | Maximum number of individual ad creatives to capture per brand (0-200). Set to `0` for a count-only check. Default `20`. |
| `proxyConfiguration` | No | Proxy settings. Leave default for best results. |

### Sample output snippet

```json
{
  "brand": "Shopify",
  "country": "US",
  "adType": "all",
  "activeStatus": "all",
  "mediaType": "all",
  "active": true,
  "adCount": 50000,
  "adCountIsLowerBound": true,
  "creatives": [
    {
      "library_id": "1238141341576372",
      "ad_url": "https://www.facebook.com/ads/library/?id=1238141341576372",
      "is_active": false,
      "startDate": "13 Jan 2026",
      "endDate": "9 Aug 2026",
      "start_date_iso": "2026-01-13",
      "end_date_iso": "2026-08-09",
      "platforms": ["Facebook", "Instagram", "Messenger"],
      "page_name": "Shopify",
      "page_url": "https://www.facebook.com/shopify/",
      "body": "When it's time to start your business, it's time for Shopify.",
      "title": "Get going and keep growing",
      "caption": "shopify.com",
      "link_url": "https://www.shopify.com/free-trial",
      "cta": "Sign up",
      "cta_type": "SIGN_UP",
      "display_format": "DCO",
      "image_url": "https://scontent.xx.fbcdn.net/...",
      "video_url": null,
      "variants_count": 1
    }
  ],
  "creativeCount": 1,
  "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=Shopify&search_type=keyword_unordered",
  "scrapedAt": "2026-10-17T15:20:00+00:00",
  "error": null
}
```

### Use cases

- **Competitor ad monitoring:** See whether a brand is running active ads and collect examples of visible copy.
- **Creative research:** Build a swipe file of CTAs, hooks, platform mix, and messaging angles.
- **Brand auditing:** Check your own active ads by country and category.
- **Agency research:** Prepare pitches with public competitor ad examples.
- **Political and issue monitoring:** Track active political or issue ad visibility in supported countries.
- **Regulated category checks:** Review housing, employment, and credit ad examples where Meta exposes them.

### Limitations

- Coverage varies by country and ad category because Meta controls what the public Ad Library exposes.
- In some regions, commercial ads may be less visible than political, issue, housing, employment, or credit ads.
- Searches are keyword searches, so results can include other advertisers whose ads mention the brand name. Filter on `page_name` if you only want the brand's own page.
- Media URLs are signed links from Meta and expire after some time; download media you want to keep.
- If a brand cannot be checked (for example a temporary Ad Library outage), it is skipped rather than returned as an empty row, and the run status lists it.
- Spend, impression, demographic, and disclaimer fields are not consistently available for standard commercial ads.
- A brand active in one country can return no results in another country filter.

### Competitor and comparison notes

- **Compared with Meta's Ad Library UI:** This actor is better for repeatable monitoring, exports, and multiple-brand checks. The UI is better for manual review of a small number of ads.
- **Compared with Meta APIs:** API access and field availability depend on Meta's permissions and ad category rules. This actor is designed for public Ad Library pages and self-serve Apify workflows.
- **Compared with social post scrapers:** This actor focuses on active paid ads, not organic posts.
- **Compared with full creative intelligence platforms:** This actor is a lightweight data extraction tool. It does not include built-in spend estimation, creative scoring, or dashboard analytics.

Pairs well with [Instagram Scraper](https://apify.com/thirdwatch/instagram-scraper?fpr=9m2cd6) for organic post monitoring and [TikTok Scraper](https://apify.com/thirdwatch/tiktok-scraper?fpr=9m2cd6) for cross-platform competitor tracking.

### FAQ

**Do I need a Facebook account?**
No. The actor uses public Meta Ad Library pages.

**Why do results differ by country?**
Meta shows different ad inventory by region, and availability can vary by ad category and local rules.

**Can I get ad spend data?**
Not reliably for standard commercial ads. Spend ranges are most commonly exposed for regulated categories such as political or issue ads where Meta provides disclosures.

**Can I get images or videos?**
Yes. Each captured ad includes `image_url`, `image_urls` and, for video ads, `video_url`.

**Can I monitor the same brands every day?**
Yes. Schedule the actor in Apify and compare counts or creative snippets over time.

### Support and custom builds

Need deduplication across runs, daily monitoring, Slack alerts, Looker/Sheets exports, or a custom ad intelligence workflow? Contact Thirdwatch at [thirdwatch.dev](https://thirdwatch.dev) or through the Apify actor support channel.

Last verified: 2026-10

# Actor input Schema

## `brands` (type: `array`):

Brand names, page names or keywords to search the Facebook Ad Library for. Each one returns one dataset item with the matching ad count and up to N ad creatives (ad text, headline, link, CTA, start/stop dates, platforms, images and videos).

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

ISO country code or 'ALL' for worldwide. Default: ALL. Common codes: US, IN, GB, CA, AU.

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

Category of ads to search. Default: all.

## `adActiveStatus` (type: `string`):

Return active ads, inactive ads, or both. Default: all.

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

Limit results to ads with a given media type. Default: all.

## `maxCreatives` (type: `integer`):

Maximum number of individual ad creatives to capture per brand (text + start date + CTA). Set to 0 to return count only.

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

Proxy settings. The default is configured for reliable access to the Facebook Ad Library.

## Actor input object example

```json
{
  "brands": [
    "allbirds"
  ],
  "country": "ALL",
  "adType": "all",
  "adActiveStatus": "all",
  "mediaType": "all",
  "maxCreatives": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# 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 = {
    "brands": [
        "allbirds"
    ],
    "country": "ALL",
    "maxCreatives": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("thirdwatch/fb-ad-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 = {
    "brands": ["allbirds"],
    "country": "ALL",
    "maxCreatives": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("thirdwatch/fb-ad-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 '{
  "brands": [
    "allbirds"
  ],
  "country": "ALL",
  "maxCreatives": 20
}' |
apify call thirdwatch/fb-ad-library-scraper --silent --output-dataset

```

## MCP server setup

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