# Facebook Ads Library E-commerce Ad Intelligence (`mibedk/facebook-ads-library-ecommerce-tracker`) Actor

Pulls live ad creatives, copy, CTAs and run dates from Meta's public Ad Library for a keyword or advertiser Page, shaped as a per-ad competitor ad-spy feed for e-commerce and DTC brands.

- **URL**: https://apify.com/mibedk/facebook-ads-library-ecommerce-tracker.md
- **Developed by:** [Mikkel Bech-Hansen](https://apify.com/mibedk) (community)
- **Categories:** E-commerce, Lead generation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$9.00 / 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.

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

## Facebook Ads Library E-commerce Ad Intelligence

Tracks what a brand or a specific advertiser Page is running on Meta's public
Ad Library and returns one clean record per ad: the creative image or video,
the copy, the call-to-action, which platforms it runs on, and how long it's
been active. Built for e-commerce and DTC teams who want a competitor ad-spy
feed instead of a raw Ad Library export - no Facebook login required, since
the Ad Library is a public transparency tool.

It drives a real headless browser to Meta's public search UI (the same page
you'd use at facebook.com/ads/library), reads the ad data straight out of the
page's own data (not screen-scraped text), and stops once it has enough ads
or the run's budget cap is reached.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `searchTerms` | array of strings | `["Nike"]` | Brand or product keywords, exactly as typed into the Ad Library search box. Matches ad copy and advertiser names - e.g. "Nike" also returns resellers' ads that mention Nike products. |
| `pageIds` | array of strings | `[]` | Numeric Facebook Page IDs. Use this to pull *every* ad from a specific advertiser instead of a keyword match. Find a Page ID via the "View all Page ads" link in the Ad Library or a Page's About panel. At least one of `searchTerms` or `pageIds` must resolve to something - the default `searchTerms` covers a first run. |
| `countryCode` | string | `"US"` | Two-letter country the ads targeted (not your own location). |
| `activeStatus` | enum | `"active"` | `active`, `inactive`, or `all`. Most competitor tracking wants active-only. |
| `maxAdsPerSearch` | integer | `20` | Stop once this many ads are found per search term / Page ID. 1-500. |
| `proxyConfiguration` | object | `{ "useApifyProxy": false }` | Off by default so the actor is free to try. See Known limitations - turn this on with the Residential group if runs start failing. |

### Output

One dataset record per ad creative. Example:

```json
{
    "adArchiveId": "1249043200627555",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1249043200627555",
    "pageId": "15087023444",
    "pageName": "Nike",
    "pageProfileUrl": "https://www.facebook.com/nike/",
    "isActive": true,
    "startDate": "2026-03-17T07:00:00.000Z",
    "endDate": "2026-08-12T07:00:00.000Z",
    "publisherPlatforms": "FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER",
    "ctaText": "Shop now",
    "ctaType": "SHOP_NOW",
    "title": "Nike: Shoes, Apparel & Stories",
    "bodyText": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año.",
    "linkUrl": "http://play.google.com/store/apps/details?id=com.nike.omega",
    "displayFormat": "DPA",
    "imageUrl": "https://scontent.xx.fbcdn.net/...",
    "videoUrl": null,
    "searchTerm": "Nike",
    "countryCode": "US",
    "scrapedAt": "2026-08-13T07:34:16.997Z"
}
```

`imageUrl`/`videoUrl` are direct CDN links from Meta and expire after a while,
so download anything you need to keep. Meta does not expose exact spend or
impression numbers for ordinary commercial ads through this surface (see
limitations) - `publisherPlatforms`, run dates, and creative content are the
reliable signals here.

### Cost

Billed per ad record delivered (`ad-scraped`, $0.01) - see `MONETIZATION.md`
for the full breakdown. A default run of 20 ads costs about **$0.20**. Set
`ACTOR_MAX_TOTAL_CHARGE_USD` on the run to cap total spend; the actor checks
the budget before every charge and stops cleanly, so you never pay for more
than you asked for.

### Known limitations

- **No exact spend or impression numbers.** Meta's public Ad Library only
  discloses spend ranges and reach estimates for political/social-issue ads.
  For ordinary commercial ads (the vast majority of e-commerce advertising)
  those fields are empty by design on Meta's side, not omitted by this actor.
- **Catalog ads show template placeholders.** Dynamic Product Ads and DCO
  creatives (common for retailers) often carry literal text like
  `{{product.name}}` in the underlying data because the real product feed is
  resolved per-viewer by Meta at render time. That's what Meta serves, not a
  parsing bug.
- **Meta rate-limits and occasionally blocks non-browser traffic.** This actor
  drives a real browser and works from a plain data-center IP in testing, but
  Meta's edge protection changes without notice. If a run starts failing with
  no ads collected, enable `proxyConfiguration` with the Residential group and
  retry.
- **Keyword search matches ad copy, not just the brand's own ads.** Searching
  "Nike" also surfaces resellers and affiliates whose ad copy mentions Nike.
  Use `pageIds` if you need ads from one advertiser only.
- **Internal Meta data shapes change.** The Ad Library's internal data layout
  isn't a stable public API and has changed before; a broken run after a Meta
  update, not stale ad data, is the most likely failure mode long-term.
- **CDN media links expire.** Save any images/video you need - Meta's URLs are
  signed and time-limited.

### Legal

This Actor is an independent, third-party tool. It is not affiliated with,
endorsed by, or sponsored by Meta Platforms, Inc.

It retrieves data by automating the public Ad Library web page, not Meta's
official Graph API - the API's `/ads_archive` endpoint only serves
political/social-issue ads to normal callers and does not cover ordinary
commercial ads (see "How it works" in the source, or `BRIEF.json`). Meta's
Terms of Service prohibit automated data collection from its products without
prior permission, and Meta has pursued legal action against scrapers in the
past. Using this Actor may not comply with Meta's terms. You are responsible
for reviewing Meta's terms and applicable law before using this Actor, and for
how you use the data it returns.

# Actor input Schema

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

Brand names or keywords to search for, exactly as you'd type them into the Ad Library search box (e.g. an advertiser or product name). Ignored for any term also covered by 'Advertiser Page IDs' below. At least one of searchTerms or pageIds must be set.

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

Numeric Facebook Page IDs to fetch all ads for (found via the 'View all Page ads' link or the Ad Library's page-info panel). Use this instead of, or alongside, searchTerms when you want every ad from specific advertisers rather than a keyword match.

## `countryCode` (type: `string`):

Two-letter country code the Ad Library should search in (this is the country the ads targeted, not your own location).

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

Which ads to include. 'active' only returns ads currently running, which is what most competitor-tracking use cases want.

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

Stop collecting once this many ads have been found for a given search term or Page ID. Keeps runs fast and predictable; raise it for deeper competitor audits.

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

Off by default so the actor is free to try. Meta rate-limits and occasionally blocks requests from data-center IPs; if runs start failing, turn this on and pick the Residential proxy group.

## Actor input object example

```json
{
  "searchTerms": [
    "Nike"
  ],
  "pageIds": [],
  "countryCode": "US",
  "activeStatus": "active",
  "maxAdsPerSearch": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `ads` (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": [
        "Nike"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("mibedk/facebook-ads-library-ecommerce-tracker").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"] }

# Run the Actor and wait for it to finish
run = client.actor("mibedk/facebook-ads-library-ecommerce-tracker").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"
  ]
}' |
apify call mibedk/facebook-ads-library-ecommerce-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mibedk/facebook-ads-library-ecommerce-tracker"
        }
    }
}

```

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/ztcZQP0reXcbvCOIb/builds/Oe1U7mQDgq4YdcNEm/openapi.json