# Facebook/Meta Ads Library Scraper API $0.5/1k (`unitbytes/meta-ads-library-scraper`) Actor

⚡ Fast & Cheap ($0.50/1k): Scrape Facebook & Instagram Ads Library by keyword, Page URL, @handle or Ad ID in seconds. Extracts HD videos, winning ads, CTAs, EU/UK reach & spend.

- **URL**: https://apify.com/unitbytes/meta-ads-library-scraper.md
- **Developed by:** [UnitBytes | Enterprise Web Data](https://apify.com/unitbytes) (community)
- **Categories:** Social media, Marketing, E-commerce
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 ad scrapeds

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 / Meta Ads Library Scraper & API

Extract public advertisements from the **Meta Ad Library** across **Facebook, Instagram, Threads, Messenger, WhatsApp, and Audience Network** in seconds—with **no login credentials required**.

Search by **keyword**, **Facebook Page URL**, **Instagram `@handle`**, **pasted Meta Ad Library URL**, or **Ad Archive ID**, and export a clean flat dataset ready for **Excel, CSV, Google Sheets, Pandas, or AI workflows**.

***

### Key Capabilities & Extracted Data

- **Flexible Multi-Input Discovery**:
  - **Keywords & Exact Phrases**: Search broad or exact-phrase keywords across any country or `ALL` worldwide.
  - **Facebook Page URLs**: Pass any brand page URL (`https://www.facebook.com/nike`, `https://www.facebook.com/shopify`)—automatically resolves the advertiser's Page ID and extracts its entire ad catalog.
  - **Instagram Profiles & Handles**: Pass `@gymshark` or `https://www.instagram.com/gymshark/` to resolve the linked advertiser account and collect its active creatives.
  - **Pasted Ad Library URLs & Single Ad IDs**: Paste filtered `facebook.com/ads/library/?...` URLs or individual `adArchiveId` strings directly.
- **Complete Creative & Funnel Intelligence**:
  - Direct **HD & SD `.mp4` video URLs**, high-resolution **creative images**, video thumbnails, and **multi-card Carousel / Dynamic Product (`carouselCards`)** breakdowns.
  - Unwrapped destination **`linkUrl`** (automatically strips `l.facebook.com` redirect wrappers), clean **`linkDomain`**, **`ctaText`** (`Shop Now`, `Learn More`), **`ctaType`**, headline **`title`**, and full **`bodyText`**.
  - **`activeDays`**, **`isLongRunningWinner`** (`30+` days active signal), and **`collationCount`** (number of active variations running the same creative).
- **Advertiser & Linked Instagram Enrichment**:
  - Facebook **`pageId`**, **`pageName`**, **`pageCategory`**, **`pageLikes`**, **`pageAbout`**, plus linked **`igUsername`**, **`igFollowers`**, and **`igVerified`**.
- **EU DSA Reach Demographics & Political Spend Transparency**:
  - **EU / UK Regulated Ads**: Extracts **`euTotalReach`**, **`payer`**, **`beneficiary`**, target age/gender/locations, and per-country **`euAgeGenderBreakdown`** matrices when provided by Meta's transparency disclosures.
  - **Political & Social Issue Ads**: Extracts **`spendText`** (`spendLower` / `spendUpper`), **`impressionsText`** (`impressionsLower` / `impressionsUpper`), **`currency`**, and **`byline`** disclaimers.

> **Upstream Data Availability Note:** Meta provides creative assets, placements, active duration, variant counts, and advertiser/Instagram profile stats on **all** public ads. Exact **`euTotalReach`** and age/gender/location breakdowns are published by Meta on ads delivered to **EU / EEA** and **UK (`GB`)** audiences (`country: "DE"`, `"FR"`, `"NL"`, `"GB"`, etc.; declared **`payer`** and **`beneficiary`** entities apply to EU DSA jurisdictions), while **`spendText`** and **`impressionsText`** ranges are published by Meta on **Political, Election & Social Issue** ads.

***

### Transparent Pay-Per-Event Pricing

Pay strictly for successfully extracted ads—`$0.00` result fee on empty searches:

| Apify Plan Tier | Price per Ad | Price per 1,000 Ads |
| :--- | :--- | :--- |
| **Free** | `$0.00075` | **`$0.75 / 1K`** |
| **Bronze** | `$0.00065` | **`$0.65 / 1K`** |
| **Silver** | `$0.00055` | **`$0.55 / 1K`** |
| **Gold / Platinum / Diamond** | `$0.00050` | **`$0.50 / 1K`** |

*(Includes a one-time `$0.0005` Actor start event per run.)*

***

### Quick Start Input Examples

#### 1. Scrape Competitor Ads by Brand Facebook Page URL & Instagram Placement

```json
{
  "urls": [
    "https://www.facebook.com/nike",
    "https://www.facebook.com/shopify"
  ],
  "country": "US",
  "activeStatus": "active",
  "mediaType": "video",
  "publisherPlatforms": ["instagram", "facebook"],
  "scrapeAdDetails": true,
  "maxItems": 50
}
```

#### 2. Search Keyword Ads in Germany with EU DSA Reach & Demographics

```json
{
  "queries": ["Zalando"],
  "country": "DE",
  "activeStatus": "active",
  "sortBy": "impressions",
  "scrapeAdDetails": true,
  "maxItems": 30
}
```

#### 3. Political & Issue Ad Spend Research

```json
{
  "queries": ["energy"],
  "country": "US",
  "adType": "political_and_issue_ads",
  "activeStatus": "all",
  "startDateMin": "2026-01-01",
  "maxItems": 50
}
```

***

### Flat Output Sample

Every dataset item uses a flat root-level schema for 1-click CSV/Excel exports:

```json
{
  "adArchiveId": "990123456789012",
  "adUrl": "https://www.facebook.com/ads/library/?id=990123456789012",
  "collationId": "440987654321000",
  "collationCount": 6,
  "isActive": true,
  "startDate": "2026-02-10T08:00:00+00:00",
  "endDate": null,
  "startTimestamp": 1770710400,
  "endTimestamp": null,
  "activeDays": 48.5,
  "isLongRunningWinner": true,
  "monitorStatus": "snapshot",
  "pageId": "100200300400",
  "pageName": "Acme Sportswear",
  "pageUrl": "https://www.facebook.com/acmesportswear/",
  "pageAlias": "acmesportswear",
  "pageCategory": "Apparel & clothing",
  "pageLikes": 412900,
  "pageAbout": "Performance running apparel and footwear.",
  "igUsername": "acmesportswear",
  "igUrl": "https://www.instagram.com/acmesportswear/",
  "igFollowers": 285400,
  "igVerified": true,
  "displayFormat": "VIDEO",
  "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
  "publisherPlatformsText": "FACEBOOK, INSTAGRAM",
  "title": "Spring Marathon Collection",
  "bodyText": "Engineered for race day comfort. Free express shipping on orders over $75.",
  "ctaText": "Shop Now",
  "ctaType": "SHOP_NOW",
  "linkUrl": "https://shop.example.com/collections/marathon",
  "linkDomain": "shop.example.com",
  "primaryImageUrl": null,
  "primaryVideoHdUrl": "https://video.example.com/v/creative_hd.mp4",
  "videoCount": 1,
  "cardCount": 0,
  "payer": "Acme Sportswear GmbH",
  "beneficiary": "Acme Sportswear GmbH",
  "euTargetsEu": true,
  "euTotalReach": 184250,
  "euGenderAudience": "All",
  "euAgeMin": 18,
  "euAgeMax": 65,
  "euTargetLocations": ["Germany", "Austria"],
  "euLocationCountriesText": "Germany, Austria",
  "euAgeGenderBreakdown": [
    {
      "country": "DE",
      "ageRange": "25-34",
      "male": 31200,
      "female": 42800,
      "unknown": 310,
      "total": 74310
    }
  ],
  "countryFilter": "DE",
  "searchQuery": "Acme Sportswear",
  "inputSource": "keyword",
  "detailLevel": "full",
  "scrapedAt": "2026-03-30T12:00:00+00:00"
}
```

***

### Multi-Batch Pagination, CSV Export & Support

- **Clean CSV / Excel Exports**: Select the **Meta Ads Library Overview** view in the Console Output tab (or append `?view=overview&format=csv` via API) for a 24-column flat spreadsheet free of nested carousel/demographic arrays.
- **Zero-Duplicate Resumption**: When `maxItems` (`>20`) or a run spending limit is reached before exhausting results, the Actor saves a compact `RESUMPTION_TOKEN` record in the run's default Key-Value Store. Pass `resumptionToken` into your next run to continue seamlessly without duplicate records.
- **Issues & Feature Requests**: Need help or have a feature request? Open a ticket directly in the **Issues** tab on this Actor page in Apify Console.

# Actor input Schema

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

Keywords, phrases, or brand names to search in Meta Ad Library (e.g. 'Nike', 'AI CRM software', 'Shopify'). Up to 50 queries per run. Ignored automatically if you paste URLs or IDs below without changing the prefill.

## `urls` (type: `array`):

Paste any Meta Ad Library search/page URL (`facebook.com/ads/library/?...`), Facebook Page URL (`https://www.facebook.com/shopify`), or Instagram profile URL (`https://www.instagram.com/gymshark/`). Up to 25 URLs/handles per run.

## `instagramHandles` (type: `array`):

Instagram advertiser handles (e.g. `@gymshark` or `loungebyzalando`) to resolve and extract all linked Instagram & Facebook ads (up to 25 URLs/handles per run).

## `adIds` (type: `array`):

Specific numeric Meta Ad Archive IDs (e.g. `1703932024036039`) to look up directly (up to 50 queries/IDs per run).

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

2-letter ISO country code (`US`, `DE`, `GB`, `FR`, `CA`, `AU`, `BR`) or `ALL` for worldwide ads. Use EU countries (`DE`, `FR`, `NL`, `AT`, `ES`, `IT`) or `GB` (`UK`) to populate total reach & age/gender demographics.

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

Filter ads by delivery status in Meta Ad Library.

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

Filter by Meta Ad Library category. Select 'Issues, Elections or Politics' for spend & impression ranges.

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

Filter ads by creative media type on Meta's server.

## `publisherPlatforms` (type: `array`):

Restrict results to specific Meta placements (`facebook`, `instagram`, `audience_network`, `messenger`, `threads`, `whatsapp`). Leave empty for all placements.

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

Match words in any order (`keyword_unordered`) or match the exact phrase (`keyword_exact_phrase`).

## `sortBy` (type: `string`):

Native Meta Ad Library server-side sort order.

## `startDateMin` (type: `string`):

Matches Meta Ad Library's native date filter (`start_date[min]`): returns ads that were active on or after this date (e.g. `2026-01-01`).

## `startDateMax` (type: `string`):

Matches Meta Ad Library's native date filter (`start_date[max]`): returns ads started on or before this date (e.g. `2026-12-31`).

## `contentLanguages` (type: `array`):

Filter ads by detected language ISO code (e.g. `en`, `de`, `es`, `fr`).

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

Enriches ads with linked Instagram handle & followers, Page bio/category/likes, payer/beneficiary disclosures, and EU/UK total reach & age/gender/country breakdowns.

## `enableChangeTracking` (type: `boolean`):

Tracks advertiser ad Archive IDs across scheduled runs in a persistent Key-Value Store (`AD_MONITOR_STATE`) to label `monitorStatus` as `baseline` (first run), `new`, or `continuing`.

## `monitorStoreName` (type: `string`):

Persistent Named Key-Value Store name (defaults automatically to `meta-ads-monitor-state` on Apify Cloud when change tracking is enabled).

## `maxItems` (type: `integer`):

Maximum total ads to return across this run.

## `resumptionToken` (type: `string`):

Paste `resumptionToken` from `RESUMPTION_TOKEN` in Key-Value Store to resume large runs from the exact cursor with zero duplicate ads.

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

Apify Residential Proxy is automatically configured on cloud runs for reliable global delivery.

## Actor input object example

```json
{
  "queries": [
    "Nike"
  ],
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "sortBy": "default",
  "scrapeAdDetails": true,
  "enableChangeTracking": false,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `overview` (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 = {
    "queries": [
        "Nike"
    ],
    "country": "US",
    "activeStatus": "active",
    "adType": "all",
    "mediaType": "all",
    "searchType": "keyword_unordered",
    "sortBy": "default",
    "scrapeAdDetails": true,
    "enableChangeTracking": false,
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("unitbytes/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 = {
    "queries": ["Nike"],
    "country": "US",
    "activeStatus": "active",
    "adType": "all",
    "mediaType": "all",
    "searchType": "keyword_unordered",
    "sortBy": "default",
    "scrapeAdDetails": True,
    "enableChangeTracking": False,
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("unitbytes/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 '{
  "queries": [
    "Nike"
  ],
  "country": "US",
  "activeStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "sortBy": "default",
  "scrapeAdDetails": true,
  "enableChangeTracking": false,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call unitbytes/meta-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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