# META Ads Library Scraper (`leadsbrary/meta-ads-library-scraper`) Actor

Scrape the Meta (Facebook & Instagram) Ads Library. Paste any Ad Library search URL or Facebook page URL. Get ad text, CTA, publisher platforms, language signals, dates and full advertiser page data. No login required.

- **URL**: https://apify.com/leadsbrary/meta-ads-library-scraper.md
- **Developed by:** [Alexandre Manguis](https://apify.com/leadsbrary) (community)
- **Categories:** Automation, Social media, Integrations
- **Features:** Limited permissions
- **Stats:** 1,103 total users, 29 monthly users, 100.0% runs succeeded, 8 bookmarks
- **User rating**: 2.89 out of 5 stars

## Pricing

from $1.30 / 1,000 ad results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Meta Ads Library Scraper

Scrape the [Meta (Facebook/Instagram) Ads Library](https://www.facebook.com/ads/library/) to extract ads from any advertiser or keyword search. Supports all built-in Ad Library filters — just paste your search URL and run.

### ✨ What you get

- **Ad content** — body text, landing domain, headline, description, snapshot URL
- **Publisher info** — which platforms the ad ran on (Facebook, Instagram, Messenger, Audience Network)
- **Language signals** — language codes detected in the ad creative (e.g. `["en", "fr"]`)
- **Delivery dates** — start date, end date, creation time
- **Advertiser page** — name, category, likes, verification status, Instagram username & followers, country
- **Ad status** — ACTIVE or INACTIVE (derived from your search filter)

> **Note:** Spend, impressions, and estimated audience size are only populated by Meta for **Special Ad Categories** (political, housing, employment). They are `null` for standard commercial ads.

#### Sample output

##### Standard commercial ad (e-commerce / sportswear)

```json
{
  "adArchiveID": "3948271054812",
  "sourceUrl": "https://www.facebook.com/ads/library/?country=US&q=nike&active_status=active",
  "pageID": "15087023444",
  "pageName": "Nike",
  "pageURL": "https://www.facebook.com/15087023444",
  "pageCategory": "Sportswear store",
  "pageLikes": 34800000,
  "pageVerified": true,
  "pageInstagramUser": "nike",
  "pageInstagramFollowers": 302000000,
  "pageCountry": "US",
  "adText": "Just Do It. Shop the latest collection.",
  "adCreativeBodies": ["Just Do It. Shop the latest collection.", "New arrivals — limited time only."],
  "publisherPlatforms": ["facebook", "instagram"],
  "adStatus": "ACTIVE",
  "languages": ["en"],
  "startDate": "2024-11-01T00:00:00+0000",
  "endDate": null,
  "adCreationTime": "2024-10-30T14:22:11+0000",
  "estimatedAudienceSize": null,
  "adLibraryURL": "https://www.facebook.com/ads/library/?id=3948271054812",
  "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=3948271054812",
  "ctaDomain": "nike.com",
  "ctaHeadline": "Shop the latest collection",
  "ctaDescription": "Free shipping on orders $50+"
}
```

##### Real-estate agency ad (multi-platform, carousel)

```json
{
  "adArchiveID": "7261039485012",
  "sourceUrl": "https://www.facebook.com/ads/library/?country=FR&q=orpi&active_status=active",
  "pageID": "204817389612445",
  "pageName": "Orpi Immobilier",
  "pageURL": "https://www.facebook.com/204817389612445",
  "pageCategory": "Real estate agency",
  "pageLikes": 42300,
  "pageVerified": false,
  "pageInstagramUser": "orpi_immobilier",
  "pageInstagramFollowers": 18500,
  "pageCountry": "FR",
  "adText": "Vendez votre bien au meilleur prix. Estimation gratuite en ligne en 2 minutes.",
  "adCreativeBodies": [
    "Vendez votre bien au meilleur prix.",
    "3 500 agences partout en France.",
    "Estimation gratuite, sans engagement."
  ],
  "publisherPlatforms": ["facebook", "instagram", "audience_network"],
  "adStatus": "ACTIVE",
  "languages": ["fr"],
  "startDate": "2025-01-15T00:00:00+0000",
  "endDate": null,
  "adCreationTime": "2025-01-14T09:11:42+0000",
  "estimatedAudienceSize": null,
  "adLibraryURL": "https://www.facebook.com/ads/library/?id=7261039485012",
  "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=7261039485012",
  "ctaDomain": "orpi.com",
  "ctaHeadline": "Estimation immobilière gratuite",
  "ctaDescription": "Obtenez une estimation en 2 minutes"
}
```

##### Special Ad Category — political (audience size populated)

```json
{
  "adArchiveID": "1092847362015",
  "sourceUrl": "https://www.facebook.com/ads/library/?country=US&ad_type=political_and_issue_ads&q=example+campaign",
  "pageID": "998877665544",
  "pageName": "Example Campaign 2024",
  "pageURL": "https://www.facebook.com/998877665544",
  "pageCategory": "Political candidate",
  "pageLikes": 87200,
  "pageVerified": true,
  "pageInstagramUser": null,
  "pageInstagramFollowers": null,
  "pageCountry": "US",
  "adText": "Our community deserves better. Join us and make your voice heard.",
  "adCreativeBodies": ["Our community deserves better. Join us and make your voice heard."],
  "publisherPlatforms": ["facebook"],
  "adStatus": "INACTIVE",
  "languages": ["en"],
  "startDate": "2024-09-01T00:00:00+0000",
  "endDate": "2024-11-05T00:00:00+0000",
  "adCreationTime": "2024-08-28T17:04:30+0000",
  "estimatedAudienceSize": { "lower_bound": 500000, "upper_bound": 600000 },
  "adLibraryURL": "https://www.facebook.com/ads/library/?id=1092847362015",
  "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=1092847362015",
  "ctaDomain": "example-campaign.com",
  "ctaHeadline": "Make your voice heard",
  "ctaDescription": "Register to vote by November 1st"
}
```

> **Note:** `estimatedAudienceSize` is only populated by Meta for **Special Ad Categories** (political, housing, employment). It is `null` for standard commercial ads.

### 🚀 Usage

#### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `startUrls` | string\[] | — | **Required.** Meta Ad Library search URLs **or** Facebook page URLs |
| `maxResults` | number | 10 | Max ads to return |
| `onlyTotalCount` | boolean | false | Return only the count, not the ads |
| `includeAboutPage` | boolean | true | Enrich with advertiser page info (category, likes, Instagram…) |
| `scrapeAdDetails` | boolean | true | Include CTA domain, headline, link description, snapshot URL |

| `activeStatus` | select | ALL | Filter by ACTIVE / INACTIVE / ALL |
| `countryFallback` | string | ALL | Country code if not detected in URL (e.g. `US`, `FR`, `GB`) |

#### Supported URL formats

**Meta Ad Library search URL** (copy-paste from ad library — all filters are preserved):

```
https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&publisher_platforms[0]=instagram&media_type=video
```

**Facebook page URL** (scrape all ads from a specific advertiser):

```
https://www.facebook.com/nike
https://www.facebook.com/15087023444
```

### 💡 Tips

- To scrape all ads from a specific brand, use their Facebook page URL — the scraper will find their Page ID and search the library for all their ads.
- You can mix Ad Library URLs and page URLs in the same run.
- Use `onlyTotalCount: true` to quickly check how many ads match your search before committing to a full scrape.
- The `countryFallback` field is only used when no `country` param is found in the URL. Set it to restrict results to a specific market.
- **`/people/` profile URLs** (e.g. `facebook.com/people/Name/ID`) point to personal profiles, not Pages. The scraper falls back to a keyword search using the name slug, so results may not be page-specific.

### 💰 Pricing

This actor charges based on results. Each ad record extracted costs **$0.0015** (= $1.50 per 1,000 ads) — billed in addition to Apify platform compute costs (typically $0.01–0.02 per 1,000 ads with 256 MB RAM).

> **Compare:** The official Meta Ads Scraper charges $3.40–$5.80 per 1,000 ads. This actor is 2–4× cheaper with the same data.

### ⚠️ Limitations & legal

- This scraper uses the **official Meta Ads Library API** (public data only). No login required. No scraping of private data.
- **`adStatus`** is derived from your search filter (ACTIVE / INACTIVE). When searching ALL statuses the field is `null`, since Meta does not return per-ad status for standard ads.
- **`estimatedAudienceSize`** is only populated by Meta for **Special Ad Categories** (political, housing, employment) — it is `null` for standard commercial ads.
- **CTA button type** (Shop Now, Sign Up…) and **ad creative images** are not exposed by Meta's Ads Library API for standard ads.
- Ad creative images/videos are not downloaded — only the snapshot URL is provided.

***

### 🔍 Keywords

Facebook ads scraper, Meta ads library scraper, Facebook ad library API, Instagram ads scraper, Meta ads extractor, Facebook advertising data, scrape Facebook ads, Facebook ads intelligence, competitor ad research, ad spy tool, Facebook ad monitoring, Meta ad archive, Facebook ads dataset, extract Facebook ads, Instagram ad library, social media ads scraper, paid ads research, Facebook marketing intelligence, ad creative scraper, Facebook page ads, Meta Business ads, Facebook ads transparency, political ads scraper, housing ads scraper, employment ads Facebook, Facebook ads by keyword, scrape ads by advertiser, Facebook ads export, Meta ads CSV export, Facebook ads JSON, ad library bulk download, Facebook ads automation, Apify Facebook scraper, competitor analysis Facebook, Facebook ads lead generation, B2B lead generation ads, ecommerce ads scraper, dropshipping competitor ads, Facebook ads analytics, Meta ads monitoring tool, brand ads Facebook, multi-country ads scraper, Facebook ads active status, Facebook ads inactive, Meta graph API ads, Facebook ads creative extractor, CTA scraper Facebook, landing page ads scraper, Facebook advertiser research

# Actor input Schema

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

Meta Ad Library search URLs (with filters embedded) **or** Facebook page URLs (e.g. `https://www.facebook.com/nike`). You can mix both types.

## `maxResults` (type: `integer`):

Maximum number of ads to return (across all URLs combined).

## `onlyTotalCount` (type: `boolean`):

If enabled, only the total number of matching ads is returned — no ad data is fetched. Useful for estimating result size before a full scrape.

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

Enrich each ad with the advertiser's Facebook page data: category, likes, verification status, Instagram username & followers, country.

## `scrapeAdDetails` (type: `boolean`):

Include full creative details: CTA link, headline, description, and an ad snapshot URL.

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

Filter ads by their delivery status. Only applied when not already specified in the Ad Library URL.

## `countryFallback` (type: `string`):

2-letter country code to use when no country is detected in the URL (e.g. `US`, `FR`, `GB`). Use `ALL` to search globally.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike"
  ],
  "maxResults": 10,
  "onlyTotalCount": false,
  "includeAboutPage": true,
  "scrapeAdDetails": true,
  "activeStatus": "ALL",
  "countryFallback": "ALL"
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing all scraped Meta Ads Library records (ad text, page info, platforms, dates, CTA details…).

# 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": [
        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("leadsbrary/meta-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": ["https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike"] }

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

```

## MCP server setup

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