# Meta Ad Library Scraper: Competitor Ads (`themineworks/meta-ad-library-scraper`) Actor

Scrape Facebook & Instagram Ad Library by keyword or advertiser. Get ad copy, image and video creative URLs, CTAs, run dates & platforms. No login, no API key. Download creatives at scale. Works in Claude, ChatGPT & any MCP AI agent.

- **URL**: https://apify.com/themineworks/meta-ad-library-scraper.md
- **Developed by:** [The Mine Works](https://apify.com/themineworks) (community)
- **Categories:** Lead generation, Social media, MCP servers
- **Stats:** 9 total users, 5 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.40 / 1,000 ads

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/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

## 📢 Meta Ad Library Scraper: Competitor Ads, No Login

### Overview

Meta Ad Library Scraper pulls every active or inactive ad Meta has for any keyword or advertiser Page ID from the Facebook and Instagram Ad Library. Feed it `lab grown diamonds` or a competitor's Page ID and get back ad copy, image and video creative URLs, CTAs, landing pages, run dates, ad status, and target platforms. No login, no Facebook Developer token, no rate-limit maze.

It's the fastest way to run competitor creative teardowns, download creative in bulk for a swipe file, or build a paid-media intel pipeline that watches every ad your competitors publish.

Reliability posture: blocked, empty, or failed searches are never charged. Every ad is pushed to your dataset first and only counted afterward, so you only pay for a record that was actually delivered.

✅ No login required | ✅ No API key | ✅ Media URLs included | ✅ MCP-ready for AI agents

### Features

Keyword or Page ID search. Search broadly by term or precisely by advertiser Page.
Full creative payload. Ad copy, image and video URLs, CTAs, landing page.
Active or historic. Choose active-only, inactive-only, or the full history.
Media type filter. Image, video, meme, or all creative types.
Country scoped. Any two-letter country code (US, IN, GB, AE, etc.).

### How it works

The actor reads the same public Meta Ad Library page the ad-library.facebook.com front-end renders, over lightweight HTTP — no browser, no login. Each search term you supply is queried independently, and Page IDs (when supplied) take priority as a precise per-advertiser filter. The public page returns about 30 ads per search; add more search terms or Page IDs to widen coverage. Each ad is flattened to one row.

Every ad record includes the original image and video creative **URLs** so you can pull creative into a swipe file or side-by-side comparison. The actor never downloads media bytes itself — it returns links — which keeps runs fast and cheap.

### 🧾 Input configuration

```json
{
  "searchTerms": ["lab grown diamonds"],
  "pageIds": [],
  "country": "US",
  "adActiveStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "maxAdsPerSearch": 100
}
```

### 📤 Output format

This is a real record captured live from the actor (Nike, US, active ads, media URLs trimmed for length):

```json
{
  "ad_archive_id": "27310692851958858",
  "page_id": "15087023444",
  "page_name": "Nike",
  "page_url": "https://www.facebook.com/nike/",
  "is_active": true,
  "start_date": "2026-07-10T07:00:00.000Z",
  "end_date": "2026-07-14T07:00:00.000Z",
  "publisher_platforms": ["FACEBOOK", "INSTAGRAM"],
  "display_format": "VIDEO",
  "ad_body": "Elevate your school look with versatile gear built for all-day comfort and style.",
  "ad_title": "Kick Off the Season",
  "ad_caption": "www.nike.com",
  "cta_text": "Shop now",
  "cta_type": "SHOP_NOW",
  "link_url": "https://www.nike.com/w/back-to-school-840ik",
  "collation_count": 1,
  "image_urls": ["https://scontent.fguz6-1.fna.fbcdn.net/v/t39.35426-6/..."],
  "video_urls": ["https://video.fguz6-1.fna.fbcdn.net/o1/v/t2/f2/m366/..."],
  "snapshot_url": "https://www.facebook.com/ads/library/?id=27310692851958858",
  "scraped_at": "2026-07-15T04:16:37.224Z"
}
```

Every ad record contains these fields:

| Field | Description |
| --- | --- |
| 🆔 `ad_archive_id` | Meta Ad Library archive ID |
| 🏢 `page_id` | Facebook Page ID of the advertiser |
| 🏷️ `page_name` | Name of the Facebook Page running the ad |
| 🔗 `page_url` | URL of the advertiser's Facebook Page |
| ✅ `is_active` | Whether the ad is currently active |
| 📅 `start_date` | ISO date the ad started running |
| 📅 `end_date` | ISO date the ad stopped, or null if still active |
| 📱 `publisher_platforms` | Array of platforms (facebook, instagram, messenger, threads, etc.) |
| 🎞️ `display_format` | Creative format as reported by Meta (VIDEO, IMAGE, DCO, CAROUSEL, etc.) |
| ✍️ `ad_body` | Primary text copy of the ad |
| 🏷️ `ad_title` | Headline text of the ad |
| 💬 `ad_caption` | Caption line shown under the creative (usually the display URL) |
| 🎯 `cta_text` | Call to action label (Shop Now, Learn More, etc.) |
| 🔘 `cta_type` | Call to action type code (SHOP\_NOW, LEARN\_MORE, etc.) |
| 🌐 `link_url` | Landing page the ad links to |
| 🗂️ `collation_count` | Number of ad variants Meta has grouped under this listing |
| 🖼️ `image_urls` | Array of image creative URLs |
| 🎥 `video_urls` | Array of video creative URLs |
| 🔍 `snapshot_url` | Direct link to the ad's live Ad Library detail page |
| 🕒 `scraped_at` | ISO timestamp of when the record was captured |

### 💼 Common use cases

**Competitor creative teardown**
Pull every active ad for a competitor and cluster the hooks, CTAs, and offers.
Track how their creative rotates across weeks and platforms.

**Category & keyword scanning**
Search a category term (`meal kit`, `sunglasses`, `lab grown diamonds`) and see who is advertising and how.
Discover new brands entering a category before they show up in Google Ads auction insights.

**Political & issue ad monitoring**
Pull political ads with spend and impression data for coverage or research.
Track messaging changes over a campaign period.

**Ad creative library / swipe file**
Download creative in bulk to build an internal swipe file for your studio or client.
Feed image and video URLs into an LLM for auto-tagging or theme analysis.

### 🚀 Getting started

1. Open the actor and add search terms, or paste one or more advertiser Page IDs for precise tracking.
2. Set the two-letter `country` (`US`, `IN`, `GB`, `AE`).
3. Choose ad status (active only, inactive only, or all) and media type.
4. Set `maxAdsPerSearch` to control cost.
5. Click Start. Records stream to the dataset as pages of results parse.

### FAQ

**Do I need a Facebook Developer account?**
No. The actor talks to the public Ad Library web endpoint and needs no API key, no app ID, and no OAuth flow.

**How do I find an advertiser's Page ID?**
Open any ad for the advertiser inside the Ad Library. The Page ID appears in the ad detail view and in the URL. Once you have it, use `pageIds` for the most precise, deduplicated results.

**How much does it cost?**
Pay per ad returned, pay as you go. No subscription, no monthly minimum.

**Can I use it in an AI agent?**
Yes. It's exposed as an MCP tool. See below.

### Use in Claude, ChatGPT & any MCP agent

```
https://mcp.apify.com/?tools=themineworks/meta-ad-library-scraper
```

Or call it programmatically with the Apify client:

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('themineworks/meta-ad-library-scraper').call({
  searchTerms: ['lab grown diamonds'],
  country: 'US',
  adActiveStatus: 'active',
  maxAdsPerSearch: 100,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### 🛠️ Complete your paid-media intel pipeline

Got the ads. Now build the wider picture:

- **[Google Trends Scraper](https://apify.com/themineworks/google-trends-pro)**: track category demand for the same keyword over time.
- **[Trustpilot Reviews Scraper](https://apify.com/themineworks/trustpilot-reviews)**: check what customers actually think of the advertisers.
- **[LinkedIn Company Scraper](https://apify.com/themineworks/linkedin-company-details)**: profile the advertiser with size, industry, HQ, and website.

Typical flow: meta-ad-library reveals the creative and offer, google-trends shows demand, trustpilot-reviews shows reality on the ground.

Questions or need a custom field set? Reach out through the Apify profile.

# Actor input Schema

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

Keywords to search the Ad Library for, e.g. a brand or product name. Each term is searched independently. Leave empty if you are searching by advertiser Page ID instead.

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

Facebook Page IDs to pull ALL ads from a specific advertiser. Find a Page ID inside any ad's Ad Library detail. Use this for precise competitor tracking. Takes priority over search terms.

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

Two-letter country code for the Ad Library region, e.g. US, IN, GB, AE. The Ad Library is country-scoped.

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

Which ads to return.

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

All commercial ads, or only political and issue ads (which carry extra spend and impression data).

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

Filter ads by creative type.

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

Maximum number of ads to collect for each search term or advertiser. The public Ad Library returns about 30 ads per search; add more searchTerms or pageIds to gather more.

## `downloadImages` (type: `boolean`):

Image creative URLs are always returned in image\_urls. This build never downloads media bytes, so this toggle is accepted for compatibility but has no effect.

## `downloadVideos` (type: `boolean`):

Video creative URLs are always returned in video\_urls. This build never downloads media bytes, so this toggle is accepted for compatibility but has no effect.

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

Apify Residential proxy is required — Meta serves datacenter IPs an anti-bot challenge, so only residential exits reach the Ad Library. Only lightweight JSON/HTML is fetched (no media), so cost per run stays low. Leave as default.

## Actor input object example

```json
{
  "searchTerms": [
    "lab grown diamonds"
  ],
  "country": "US",
  "adActiveStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "maxAdsPerSearch": 10,
  "downloadImages": false,
  "downloadVideos": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "searchTerms": [
        "lab grown diamonds"
    ],
    "country": "US",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("themineworks/meta-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 = {
    "searchTerms": ["lab grown diamonds"],
    "country": "US",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("themineworks/meta-ad-library-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 '{
  "searchTerms": [
    "lab grown diamonds"
  ],
  "country": "US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call themineworks/meta-ad-library-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/57SKI9Cz02tOmI7Hi/builds/3JX5dTdck2hSIOKgj/openapi.json