# Facebook Meta Ads Library Scraper (`karamelo/facebook-ads-library-scraper`) Actor

Scrape Meta & Facebook Ad Library for competitor ad intelligence. Search by keyword, Page URL, or library link with country, status, and media filters. Extract full ad copy, creatives, links, platforms, and spend. 100% automated with no login or Meta API token needed.

- **URL**: https://apify.com/karamelo/facebook-ads-library-scraper.md
- **Developed by:** [karamelo](https://apify.com/karamelo) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 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.

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

### Overview

Facebook Ads Library Scraper extracts public ad records from the Meta / Facebook Ad Library, including advertiser information, ad copy, creative media, links, active dates, and platform placements. Provide search keywords, advertiser Facebook Page URLs, or direct Ad Library search URLs to receive structured datasets ready for analysis and export. Digital marketers, brand strategists, and competitive intelligence teams can monitor competitor campaigns, creative trends, and messaging without needing a Facebook account or Meta API credentials.

### Quick start

1. Open **Facebook Ads Library Scraper** on the [Apify Store](https://apify.com/karamelo/facebook-ads-library-scraper).
2. Enter one or more keywords in **Search keywords** (e.g. `shopify`), or paste advertiser Facebook Page URLs (e.g. `https://www.facebook.com/shopify`).
3. Set your target **Country** (default: `US`, or `ALL` for global coverage) and adjust **Max ads** if needed.
4. Click **Start** to run the scraper.
5. Once complete, view the results in the dataset tab and export as JSON, CSV, Excel, or HTML.

#### Minimal input example

```json
{
  "searchQueries": [
    "shopify"
  ],
  "country": "US",
  "activeStatus": "all",
  "mediaType": "all",
  "maxAds": 10
}
```

### Data extracted

Each row in the dataset represents a unique Facebook Ad Library ad. Results are flattened for easy analysis in spreadsheets and database tools.

#### Representative output record

```json
{
  "adArchiveId": "1238141341576372",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1238141341576372",
  "pageId": "20409006880",
  "pageName": "Shopify",
  "pageUrl": "https://www.facebook.com/shopify/",
  "pageProfilePictureUrl": "https://scontent.xx.fbcdn.net/v/t39.35426-6/sample.jpg",
  "pageCategories": [
    "Software",
    "E-commerce"
  ],
  "pageLikeCount": 4547149,
  "isActive": false,
  "startDate": "2026-01-13",
  "endDate": "2026-08-09",
  "platforms": [
    "FACEBOOK",
    "INSTAGRAM",
    "MESSENGER"
  ],
  "bodyText": "When it's time to start your business, it's time for Shopify.",
  "title": "Get going and keep growing",
  "ctaText": "Sign up",
  "ctaType": "SIGN_UP",
  "linkUrl": "https://www.shopify.com/free-trial",
  "linkCaption": "shopify.com",
  "linkDescription": "Start your free trial today.",
  "displayFormat": "IMAGE",
  "imageUrls": [
    "https://scontent.xx.fbcdn.net/v/t39.35426-6/ad_creative_image.jpg"
  ],
  "videoUrls": [],
  "videoPreviewUrls": [],
  "categories": [
    "UNKNOWN"
  ],
  "containsAiMedia": false,
  "impressions": null,
  "spend": null,
  "currency": null,
  "gatedType": "ELIGIBLE",
  "collationCount": 1,
  "cardsCount": 0
}
```

#### Dataset field reference

| Field | Type | Description |
|---|---|---|
| `adArchiveId` | string | Unique Facebook Ad Library identifier. |
| `adLibraryUrl` | string | Direct link to view the ad on Facebook Ad Library. |
| `pageId` | string | Facebook Page identifier for the advertiser. |
| `pageName` | string | Name of the advertiser Facebook Page. |
| `pageUrl` | string | Direct URL of the advertiser Facebook Page. |
| `pageProfilePictureUrl` | string | URL of the advertiser Page profile picture. |
| `pageCategories` | array | Business categories associated with the advertiser Page. |
| `pageLikeCount` | number | Public follower / like count for the advertiser Page. |
| `isActive` | boolean | Whether the ad is currently active and running. |
| `startDate` | string | First date the ad was observed running (`YYYY-MM-DD`). |
| `endDate` | string | Last date the ad ran (`YYYY-MM-DD`), or `null` if currently active. |
| `platforms` | array | Meta platforms where the ad ran (`FACEBOOK`, `INSTAGRAM`, `MESSENGER`, etc.). |
| `bodyText` | string | Primary ad copy text. |
| `title` | string | Headline or title of the ad creative. |
| `ctaText` | string | Visible call-to-action button text (e.g. `Shop Now`, `Sign up`). |
| `ctaType` | string | Facebook call-to-action identifier (e.g. `SHOP_NOW`, `SIGN_UP`). |
| `linkUrl` | string | Destination landing page URL linked by the ad. |
| `linkCaption` | string | Display caption shown for the destination URL. |
| `linkDescription` | string | Accompanying description for the destination link. |
| `displayFormat` | string | Ad format reported by Facebook (`IMAGE`, `VIDEO`, `DCO`, `CAROUSEL`). |
| `imageUrls` | array | Direct URLs to ad creative images. |
| `videoUrls` | array | Direct URLs to ad videos when available. |
| `videoPreviewUrls` | array | Thumbnail preview URLs for ad videos. |
| `categories` | array | Special ad categories (e.g. `EMPLOYMENT`, `HOUSING`, `POLITICAL`). |
| `containsAiMedia` | boolean | Whether Meta flags the ad creative as AI-generated media. |
| `impressions` | string | Public impression bracket (available for political/issue ads). |
| `spend` | object | Estimated spend bounds (`lowerBound`, `upperBound`) for political/issue ads. |
| `currency` | string | Currency code for spend estimates when available. |
| `gatedType` | string | Content eligibility classification. |
| `collationCount` | number | Number of creative variations in the ad collation group. |
| `cardsCount` | number | Number of cards for carousel ad creatives. |

### Input parameters

| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
| `searchQueries` | array | `["shopify"]` | No | List of search keywords to query. Each keyword runs a separate search. |
| `pageUrls` | array | `[]` | No | Facebook Page URLs to extract ads from specific advertisers. |
| `adsLibraryUrls` | array | `[]` | No | Facebook Ad Library results URLs copied from browser searches. |
| `country` | string | `"US"` | No | Two-letter ISO country code (e.g. `US`, `GB`, `DE`, `FR`) or `ALL`. |
| `activeStatus` | string | `"all"` | No | Filter ads by status: `all`, `active`, or `inactive`. |
| `mediaType` | string | `"all"` | No | Filter ads by media type: `all`, `image_and_meme`, or `video`. |
| `onlyAdsNewerThan` | string | `""` | No | Inclusive start date bound (`YYYY-MM-DD` or relative such as `30 days`). |
| `onlyAdsOlderThan` | string | `""` | No | Inclusive end date bound (`YYYY-MM-DD` or relative such as `90 days`). |
| `maxAds` | integer | `100` | No | Maximum ads to collect per task (safety cap: 1 to 500). |

### Search modes and options

- **Search by keyword:** Enter keywords representing products, services, or brand names. The scraper searches the selected country and status.
- **Search by advertiser:** Enter public Facebook Page URLs (such as `https://www.facebook.com/shopify/`) to monitor specific competitors.
- **Search by direct URL:** Paste full URLs copied from the Facebook Ad Library interface. Embedded parameters (query, page ID, country, status, media type) are respected.
- **Date filtering:** Use `onlyAdsNewerThan` and `onlyAdsOlderThan` to bound the ad activity window. Active ads with no end date are evaluated as active through the current date.

### Use cases

- **Competitor ad monitoring:** Track which creatives and headlines competitors run over time, how long campaigns last, and when new offers launch.
- **Creative inspiration:** Discover high-performing ad concepts, video structures, and call-to-action hooks in specific industries.
- **Brand protection:** Verify authorized partner representation and detect unauthorized brand usage across ad networks.
- **Market research:** Compare messaging angles and value propositions across international markets by varying the country filter.

### Programmatic usage with Apify API

You can trigger runs and access datasets programmatically using the Apify API in Node.js, Python, or cURL.

#### Node.js

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

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

const run = await client.actor('karamelo/facebook-ads-library-scraper').call({
  searchQueries: ['shopify'],
  country: 'US',
  maxAds: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Retrieved ${items.length} ads:`, items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')

run = client.actor('karamelo/facebook-ads-library-scraper').call(run_input={
    'searchQueries': ['shopify'],
    'country': 'US',
    'maxAds': 20,
})

dataset_items = client.dataset(run['defaultDatasetId']).list_items().items
print(f"Retrieved {len(dataset_items)} ads")
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/karamelo~facebook-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQueries": ["shopify"],
    "country": "US",
    "maxAds": 20
  }'
```

### Integrations

Export your scraped ad data to other tools directly from Apify Console:

- **Google Sheets:** Sync new ad rows to a Google Spreadsheet on every scheduled run.
- **Airtable:** Create visual competitor ad galleries with image and video preview links.
- **Slack & Discord:** Receive webhook alerts when competitor campaigns launch.
- **Make / Zapier / n8n:** Trigger automated workflows, AI summarization, or database updates when new ad records are pushed.

### Limitations and guidelines

- **Safety caps:** Up to 20 search tasks per run, and up to 500 ads per search task. For larger extractions, divide keywords across multiple runs.
- **Public data:** Extracts only publicly accessible ads from the Facebook Ad Library transparency portal.
- **Spend and impressions:** Spend and impression brackets are provided only for ads covering social issues, elections, or politics, as defined by Meta transparency reporting rules. Standard commercial ads do not report spend estimates.
- **Disclaimer:** Facebook and Meta are trademarks of Meta Platforms, Inc. This Actor is an independent tool accessing public transparency data and is not affiliated with or endorsed by Meta.

# Actor input Schema

## `searchQueries` (type: `array`):

Enter keywords to search for in the Ad Library (e.g. "shopify", "running shoes"). Each keyword runs a separate search. Safety cap: up to 20 total search/page/Ads Library URL tasks per run.

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

Enter Facebook Page URLs to scrape ads from specific advertisers (e.g. "https://www.facebook.com/shopify"). Safety cap: up to 20 total search/page/Ads Library URL tasks per run.

## `adsLibraryUrls` (type: `array`):

Paste Facebook Ads Library results URLs copied from facebook.com/ads/library/. Embedded URL filters are used for this input. Safety cap: up to 20 total search/page/Ads Library URL tasks per run.

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

ISO country code to search in (e.g. "US", "GB", "DE"). Use "ALL" for all countries.

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

Filter by ad status.

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

Filter by ad media type.

## `onlyAdsNewerThan` (type: `string`):

Optional inclusive lower bound for the ad activity interval. Use YYYY-MM-DD or a positive relative duration such as "30 days". An ad matches when its start/end activity interval overlaps the requested date window.

## `onlyAdsOlderThan` (type: `string`):

Optional inclusive upper bound for the ad activity interval. Use YYYY-MM-DD or a positive relative duration such as "90 days". Active ads with no end date are handled as still active.

## `maxAds` (type: `integer`):

Maximum number of ads to extract per search query, page URL, or Ads Library URL. Safety cap: 500 per search/page task.

## Actor input object example

```json
{
  "searchQueries": [
    "shopify"
  ],
  "pageUrls": [],
  "adsLibraryUrls": [],
  "country": "US",
  "activeStatus": "all",
  "mediaType": "all",
  "onlyAdsNewerThan": "",
  "onlyAdsOlderThan": "",
  "maxAds": 10
}
```

# Actor output Schema

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

View the Facebook ads returned by this run.

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

Facebook ads with advertiser, creative, activity, platform, and destination fields.

# 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 = {
    "searchQueries": [
        "shopify"
    ],
    "pageUrls": [],
    "adsLibraryUrls": [],
    "country": "US",
    "activeStatus": "all",
    "mediaType": "all",
    "onlyAdsNewerThan": "",
    "onlyAdsOlderThan": "",
    "maxAds": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("karamelo/facebook-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 = {
    "searchQueries": ["shopify"],
    "pageUrls": [],
    "adsLibraryUrls": [],
    "country": "US",
    "activeStatus": "all",
    "mediaType": "all",
    "onlyAdsNewerThan": "",
    "onlyAdsOlderThan": "",
    "maxAds": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("karamelo/facebook-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 '{
  "searchQueries": [
    "shopify"
  ],
  "pageUrls": [],
  "adsLibraryUrls": [],
  "country": "US",
  "activeStatus": "all",
  "mediaType": "all",
  "onlyAdsNewerThan": "",
  "onlyAdsOlderThan": "",
  "maxAds": 10
}' |
apify call karamelo/facebook-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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