# Meta Ad Library collector (`data_dino/fb-meta-ads`) Actor

Collect structured public ads from the Meta Ad Library by keyword, page, country, status, and ad category without requiring a Meta API key.

- **URL**: https://apify.com/data\_dino/fb-meta-ads.md
- **Developed by:** [Data Dino](https://apify.com/data_dino) (community)
- **Categories:** Social media, E-commerce, Lead generation
- **Stats:** 2 total users, 1 monthly users, 60.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 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/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 collector

Collect structured public advertisements from the Meta (Facebook) Ad Library for market research, creative monitoring, competitor analysis, and campaign discovery. Search by keyword, exact phrase, country, special ad category, or Facebook page without supplying a Meta API key.

### Features

- Searches active, inactive, or all ads for a selected country.
- Resolves Facebook page URLs, page names, or numeric page IDs.
- Filters by ad category, delivery dates, media type, impressions, spend, language, and publisher platform.
- Returns page metadata, creative text and media URLs, delivery dates, impression and spend ranges, targeting signals, and collection timestamps.
- Optionally includes the raw GraphQL response for downstream analysis.
- Pushes one structured ad record per dataset item.

Meta's Ad Library endpoint is an internal web endpoint and may change or apply rate limits. Results represent information publicly exposed by Meta at collection time; unavailable fields remain null or empty.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `query` | string | `solar panels` | Keyword or phrase to search; blank searches all matching ads. |
| `country` | string | `US` | Two-letter ISO country code. |
| `adType` | enum | `all` | `all`, `political`, `housing`, `employment`, or `credit`. |
| `status` | enum | `active` | `active`, `inactive`, or `all`. |
| `searchType` | enum | `keyword` | `keyword`, `exact`, or `page`. |
| `sortBy` | enum | `impressions` | `impressions` or `relevancy`. |
| `pageIds` | array | `[]` | Numeric Facebook page IDs to restrict results. |
| `pageUrl` | string | empty | Facebook page URL or numeric page path. |
| `pageName` | string | empty | Page name to resolve through Meta typeahead. |
| `maxResults` | integer | `20` | Maximum records; `0` means unlimited. |
| `pageSize` | integer | `10` | Ads requested per page, from 1 to 30. |
| `delay` | number | `2` | Base delay between paginated requests in seconds. |
| `timeout` | integer | `30` | Per-request timeout in seconds. |
| `includeRaw` | boolean | `false` | Include the raw GraphQL payload under `raw_data`. |
| `minImpressions`, `maxImpressions` | integer | null | Optional impression bounds. |
| `minSpend`, `maxSpend` | integer | null | Optional spend bounds in the ad's currency. |
| `startDate`, `endDate` | string | empty | Optional ISO 8601 delivery-start bounds. |
| `mediaType` | enum | `all` | `all`, `image`, `video`, `meme`, or `none`. |
| `publisherPlatforms` | array | `[]` | Platform filters such as `facebook` or `instagram`. |
| `languages` | array | `[]` | Creative language filters. |
| `hasVideo`, `hasImage` | boolean | `false` | Require detected video or image media. |

Example:

```json
{
  "query": "solar panels",
  "country": "US",
  "status": "active",
  "maxResults": 25,
  "mediaType": "video"
}
```

### Output

Each dataset item is an ad record. A typical item includes:

```json
{
  "id": "1234567890",
  "page": {
    "id": "987654321",
    "name": "Example Brand",
    "page_url": "https://www.facebook.com/example"
  },
  "is_active": true,
  "ad_status": "ACTIVE",
  "creatives": [
    {
      "body": "Example ad copy",
      "title": "Learn more",
      "image_url": "https://example.invalid/image.jpg"
    }
  ],
  "impressions": { "lower_bound": 1000, "upper_bound": 4999 },
  "publisher_platforms": ["facebook", "instagram"],
  "collection_source": "meta_ads_library"
}
```

# Actor input Schema

## `query` (type: `string`):

Keyword or phrase to search in the Meta Ad Library. Leave blank to search all ads matching the other filters.

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

Two-letter ISO country code used by the Ad Library search, such as US, GB, CA, or AU.

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

Restrict results to a special ad category or collect all ad categories.

## `status` (type: `string`):

Return active ads, inactive ads, or both.

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

Choose unordered keyword matching, exact phrase matching, or page matching.

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

Sort by Meta relevance or by total impressions when supported by the Ad Library.

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

Optional numeric Facebook page IDs to restrict the search. Use pageUrl or pageName when you do not know the numeric ID.

## `pageUrl` (type: `string`):

Optional Facebook page URL or numeric page path. The actor extracts its numeric page ID and searches that page's ads.

## `pageName` (type: `string`):

Optional page name to resolve through Meta typeahead before collecting that page's ads.

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

Maximum number of ad records to return. Use 0 for no limit.

## `pageSize` (type: `integer`):

Number of ads requested from Meta per GraphQL page. Smaller values can be useful when requests are rate limited.

## `delay` (type: `number`):

Base delay between paginated requests. A small random jitter is added by the scraper.

## `timeout` (type: `integer`):

Timeout for each Meta request.

## `includeRaw` (type: `boolean`):

Include the raw GraphQL ad payload under raw\_data. This can make dataset records substantially larger.

## `minImpressions` (type: `integer`):

Optional lower bound for impression filtering.

## `maxImpressions` (type: `integer`):

Optional upper bound for impression filtering.

## `minSpend` (type: `integer`):

Optional lower bound for reported spend filtering, in the ad's currency.

## `maxSpend` (type: `integer`):

Optional upper bound for reported spend filtering, in the ad's currency.

## `startDate` (type: `string`):

Optional ISO 8601 date or datetime; exclude ads that started before this value.

## `endDate` (type: `string`):

Optional ISO 8601 date or datetime; exclude ads that started after this value.

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

Optionally keep only image, video, meme, or media-free ads.

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

Optional platform names such as facebook, instagram, audience\_network, or messenger.

## `languages` (type: `array`):

Optional language codes used to filter returned creatives.

## `hasVideo` (type: `boolean`):

When enabled, keep only ads with detected video creative media.

## `hasImage` (type: `boolean`):

When enabled, keep only ads with detected image creative media.

## Actor input object example

```json
{
  "query": "solar panels",
  "country": "US",
  "adType": "all",
  "status": "active",
  "searchType": "keyword",
  "sortBy": "impressions",
  "pageIds": [],
  "pageUrl": "",
  "pageName": "",
  "maxResults": 20,
  "pageSize": 10,
  "delay": 2,
  "timeout": 30,
  "includeRaw": false,
  "startDate": "",
  "endDate": "",
  "mediaType": "all",
  "publisherPlatforms": [],
  "languages": [],
  "hasVideo": false,
  "hasImage": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

Each dataset item is a structured Meta Ad Library ad record with page, creative, delivery, impression, spend, and collection metadata.

# 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 = {
    "query": "solar panels",
    "country": "US",
    "adType": "all",
    "status": "active",
    "searchType": "keyword",
    "sortBy": "impressions",
    "pageIds": [],
    "pageUrl": "",
    "pageName": "",
    "maxResults": 20,
    "pageSize": 10,
    "delay": 2,
    "timeout": 30,
    "includeRaw": false,
    "startDate": "",
    "endDate": "",
    "mediaType": "all",
    "publisherPlatforms": [],
    "languages": [],
    "hasVideo": false,
    "hasImage": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("data_dino/fb-meta-ads").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 = {
    "query": "solar panels",
    "country": "US",
    "adType": "all",
    "status": "active",
    "searchType": "keyword",
    "sortBy": "impressions",
    "pageIds": [],
    "pageUrl": "",
    "pageName": "",
    "maxResults": 20,
    "pageSize": 10,
    "delay": 2,
    "timeout": 30,
    "includeRaw": False,
    "startDate": "",
    "endDate": "",
    "mediaType": "all",
    "publisherPlatforms": [],
    "languages": [],
    "hasVideo": False,
    "hasImage": False,
}

# Run the Actor and wait for it to finish
run = client.actor("data_dino/fb-meta-ads").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 '{
  "query": "solar panels",
  "country": "US",
  "adType": "all",
  "status": "active",
  "searchType": "keyword",
  "sortBy": "impressions",
  "pageIds": [],
  "pageUrl": "",
  "pageName": "",
  "maxResults": 20,
  "pageSize": 10,
  "delay": 2,
  "timeout": 30,
  "includeRaw": false,
  "startDate": "",
  "endDate": "",
  "mediaType": "all",
  "publisherPlatforms": [],
  "languages": [],
  "hasVideo": false,
  "hasImage": false
}' |
apify call data_dino/fb-meta-ads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data_dino/fb-meta-ads"
        }
    }
}

```

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/NnjCxKtl3YQwecHEv/builds/27yf7yDDn4FmeAQCK/openapi.json