# Meta Ads Library Scraper: Facebook & Instagram Ads (`northloop-labs/meta-ads-library-scraper`) Actor

Scrape the Meta Ads Library for Facebook and Instagram ads by keyword, Page or Ad Library URL: ad copy, creatives, CTA, platforms, start and end dates, landing pages and advertiser details. Optional only-new monitor for competitor tracking.

- **URL**: https://apify.com/northloop-labs/meta-ads-library-scraper.md
- **Developed by:** [Northloop Labs](https://apify.com/northloop-labs) (community)
- **Categories:** Social media, Lead generation, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.15 / 1,000 ad saveds

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

## Meta Ads Library Scraper: Facebook & Instagram Ads

Scrape the public [Meta Ads Library](https://www.facebook.com/ads/library/) for **Facebook and Instagram ads** (and other Meta placements Meta lists) by **keyword**, **Facebook Page** or **Ad Library URL**. For every ad you get the **ad copy**, **CTA**, **creative image/video URLs**, **platforms**, **start/end dates**, **landing URL**, **Page name/ID** and a link back to the Ad Library.

**Track new competitor ads:** turn on *Only new ads*, schedule the Actor, and each run saves only ads that were not seen before (state lives in a key-value store in **your** Apify account).

No Facebook login and no Meta developer app.

### What you can use it for

- **Competitor research:** see the creatives and offers rivals are running on Meta right now.
- **Ad creative swipe files:** collect image and video ads with copy for inspiration or AI analysis.
- **Brand / agency monitoring:** schedule daily runs and get only new ads for watched keywords or Pages.
- **Political / issue transparency:** filter to political and issue ads where Meta exposes them.

### How to scrape Meta Ads Library ads

| Field | Description |
|---|---|
| `searchTerms` | Keywords (unordered match), one per line |
| `pageIds` | Numeric Facebook Page IDs |
| `pageUrls` | Facebook Page URLs (`https://www.facebook.com/nike`) |
| `startUrls` | Full Ads Library search or single-ad URLs |
| `country` | 2-letter code (`US`, `GB`, `DE`...) or `ALL` |
| `activeStatus` | `ACTIVE`, `INACTIVE` or `ALL` |
| `adType` | `ALL` or `POLITICAL_AND_ISSUE_ADS` |
| `mediaType` | `ALL`, `IMAGE`, `VIDEO` or `MEME` |
| `maxResults` | Hard cap on ads saved (and charged) |
| `maxAdsPerSearch` | Optional cap per keyword / Page / URL |
| `onlyNew` | Skip ads already in the monitor store |
| `monitorStoreName` | KV store name (default `meta-ads-monitor`) |
| `proxyCountry` | Residential exit country (default = search country) |

#### Input example

```json
{
  "searchTerms": ["nike", "adidas"],
  "country": "US",
  "activeStatus": "ACTIVE",
  "mediaType": "ALL",
  "maxResults": 50
}
```

Page watch:

```json
{
  "pageUrls": ["https://www.facebook.com/nike"],
  "country": "US",
  "onlyNew": true,
  "maxResults": 100
}
```

#### Output example

```json
{
  "adArchiveId": "1234567890",
  "pageId": "15087023444",
  "pageName": "Nike",
  "isActive": true,
  "displayFormat": "IMAGE",
  "bodyText": "Just Do It.",
  "title": "Nike Air",
  "ctaText": "Shop Now",
  "linkUrl": "https://www.nike.com/",
  "imageUrls": ["https://scontent.xx.fbcdn.net/..."],
  "videoUrls": [],
  "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
  "startDate": "2024-11-14T00:00:00.000Z",
  "endDate": null,
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1234567890",
  "searchLabel": "keyword \"nike\"",
  "country": "US",
  "scrapedAt": "2026-10-24T12:00:00.000Z"
}
```

Spend, impressions and reach fields are filled when Meta publishes them (often for political / EU transparency ads); otherwise they stay null.

### Pricing

Pay per event (platform usage included; Apify takes its usual Store cut from the prices below):

| Event | Price | When |
|---|---|---|
| Actor start | **$0.005** per GB of memory | Every run (default **2 GB** → $0.01) |
| Meta Ads Library session | **$0.15** | Once per run, **only** after Meta accepts a browser session. If every attempt is blocked, this is **not** charged. |
| Ad saved | **$0.0045** ($4.50 / 1,000) | Each unique ad written to the dataset. Duplicates and already-seen ads in only-new mode are free. |

**Examples:** 50 ads ≈ $0.01 + $0.15 + $0.225 = **~$0.39**. 1,000 ads in one session ≈ $0.01 + $0.15 + $4.50 = **~$4.66**.

**No OCR charge.** Ad copy (`bodyText`, title, CTA) comes from Meta's public Ads Library fields (GraphQL / page JSON). Image and video creatives are returned as URLs only — we do **not** run OCR on creatives, so there is no separate OCR event and no hidden compute cost bundled into `ad-result`.

Undercuts Apify's official Facebook Ads Library Scraper on Free ($4.50 vs $5.80 / 1k ads) and stays competitive at Gold after Store discounts, with a flat session fee and an only-new monitor.

### Reliability notes

- Meta serves a client challenge (`__rd_verify_`) to bare HTTP clients. This Actor opens a real Camoufox browser over **Apify residential proxies**, then reads Ads Library GraphQL responses.
- Meta changes GraphQL shapes often. When a run returns 0 ads for a query that should have results, open an issue — we patch quickly.
- Session waves: if Meta blocks every residential IP in a run, nothing is saved and **no session fee** is charged. Retry in a few minutes or change `proxyCountry`.

### Use with AI agents, MCP, Make, Zapier, n8n and the API

#### AI agents and the Apify MCP server

```text
https://mcp.apify.com?tools=northloop-labs/meta-ads-library-scraper
```

#### API

```bash
curl -X POST "https://api.apify.com/v2/acts/northloop-labs~meta-ads-library-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["nike"], "country": "US", "maxResults": 30}'
```

```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("northloop-labs/meta-ads-library-scraper").call(
    run_input={"searchTerms": ["nike"], "country": "US", "maxResults": 30}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Data & privacy

- The Actor reads only the **public Meta Ads Library**, which Meta publishes for transparency. It collects ad creatives, ad text, Page names/IDs, platforms and dates that Meta shows publicly.
- It collects **no personal data** about people who saw or clicked ads (no targeting audiences for commercial ads beyond what Meta already shows on the page).
- Results are written **only** to the run's default Apify dataset in your account. In only-new mode, seen ad IDs are kept in a key-value store in **your** account (`monitorStoreName`), which you can delete anytime. No external storage or webhooks.

### Is it legal to scrape the Meta Ads Library?

The Ads Library is a public transparency tool. The Actor reads it the same way a browser does, at a moderate pace, through residential proxies. Ad creatives can be protected by copyright and trademarks — use them for research and analysis, not to republish as your own. This is not legal advice; check the rules that apply to your use.

### FAQ

#### How much does it cost?

About **$4.66 per 1,000 ads** in a single session at the default 2 GB memory, including the session fee. Smaller runs pay the same session fee once. Store discounts (Bronze/Silver/Gold) lower the per-ad price further; the session fee stays flat.

#### Why is there a session fee?

Meta requires a trusted browser session. Opening one uses residential proxy traffic. The fee is charged only when that session succeeds.

#### Does it need a Facebook login?

No.

#### Does it OCR ad images?

No. Text fields come from Meta's public data. Creative image/video URLs are included so you can download or OCR them yourself if you need to.

#### Can I watch one brand every day?

Yes: set `pageUrls` or `pageIds`, turn on `onlyNew`, save a task and schedule it.

### How this Actor was made

This Actor was made with AI. An AI agent wrote and tested the code, this README and the store listing, and a human owns and maintains the Actor.

### More Actors from Northloop Labs

- [X Ads Transparency Scraper: X (Twitter) Ads Repository](https://apify.com/northloop-labs/x-ads-transparency-scraper): X (Twitter) ads from the Ads Repository, guest access, no login.
- [Luma, Eventbrite & Meetup Events Scraper](https://apify.com/northloop-labs/tech-events-finder): tech, AI and startup events from Luma, Eventbrite and Meetup.
- [Greenhouse, Lever, Ashby & Workable Jobs Scraper](https://apify.com/northloop-labs/company-jobs-finder): open jobs from company career pages.
- [Google Ads Transparency Center Scraper](https://apify.com/northloop-labs/google-ads-transparency-library): a company's ads from the Google Ads Transparency Center.
- [Podcast Transcriber for RSS & Apple Podcasts](https://apify.com/northloop-labs/podcast-transcriber): podcast transcripts with timestamps and SRT subtitles.
- [EU TED & UK Find a Tender Scraper](https://apify.com/northloop-labs/public-tenders-monitor): UK and EU public tenders with daily alerts.
- [Google Trends Scraper: Keywords, Regions & Related Queries](https://apify.com/northloop-labs/google-trends-scraper): bulk Google Trends with comparisons and rising-query alerts.
- [YouTube Transcript Scraper: Captions, Subtitles & Text](https://apify.com/northloop-labs/youtube-transcript-scraper): YouTube transcripts with captions or Whisper, timestamps and SRT.
- [Google Maps Leads Scraper: Emails, Phones & Socials](https://apify.com/northloop-labs/google-maps-leads-scraper): local business leads with emails, phones, socials and a lead score.
- [Home Depot Scraper: Products, Prices, Stock & Reviews](https://apify.com/northloop-labs/home-depot-scraper): Home Depot products, prices, store stock and reviews.

### Feedback

Want TikTok or LinkedIn ad libraries, richer EU transparency fields, or a filter that's missing? Open an issue in the **Issues** tab.

# Actor input Schema

## `searchTerms` (type: `array`):

Keywords to search in the Meta Ads Library (unordered match). One per line. Example: nike, meal kit, crypto wallet.

## `pageIds` (type: `array`):

Numeric Facebook Page IDs to scrape all ads for (view_all_page_id). Prefer this when you already know the Page ID.

## `pageUrls` (type: `array`):

Facebook Page URLs such as https://www.facebook.com/nike. The Actor resolves the Page ID when possible.

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

Full Meta Ads Library search or single-ad URLs. Filters in the URL (country, status, media type) are used as-is for that URL.

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

2-letter country code for keyword and Page searches (US, GB, DE, FR, RO...). Use ALL for every country Meta lists.

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

Only active ads, only inactive, or all.

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

All ads, or only political / issue ads (where Meta exposes them).

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

Filter by creative format.

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

Stop after this many unique ads are saved. You are charged only for ads saved, never more than this.

## `maxAdsPerSearch` (type: `integer`):

Optional cap per keyword, Page or start URL. 0 = share Max ads evenly, then fill leftovers.

## `onlyNew` (type: `boolean`):

Skip ads already seen in the monitor store. The first run sets the baseline. Schedule daily or weekly to track new competitor ads.

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

Key-value store in your Apify account that remembers which ad archive IDs were already seen.

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

Residential proxy exit country (ISO code). US works best for the Ads Library. Leave empty to use the search country.

## `maxSessionAttempts` (type: `integer`):

How many residential browser sessions to try if Meta challenges one. Each failed attempt is free (no session fee).

## Actor input object example

```json
{
  "searchTerms": [
    "nike"
  ],
  "country": "US",
  "activeStatus": "ACTIVE",
  "adType": "ALL",
  "mediaType": "ALL",
  "maxResults": 10,
  "maxAdsPerSearch": 0,
  "onlyNew": false,
  "monitorStoreName": "meta-ads-monitor",
  "proxyCountry": "",
  "maxSessionAttempts": 4
}
```

# Actor output Schema

## `overview` (type: `string`):

Page, copy, platforms, dates and Ad Library link.

## `creatives` (type: `string`):

Images, videos, CTA and landing URL.

## `all` (type: `string`):

Every field for every ad.

## `runSummary` (type: `string`):

Counts per search, session stats and errors.

# 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 = {
    "searchTerms": [
        "nike"
    ],
    "country": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("northloop-labs/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 = {
    "searchTerms": ["nike"],
    "country": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("northloop-labs/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 '{
  "searchTerms": [
    "nike"
  ],
  "country": "US"
}' |
apify call northloop-labs/meta-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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