# Facebook Ads Scraper with Cookies (`masoncode/facebook-ads-scraper-with-cookies`) Actor

Scrape Meta Ads Library ads worldwide by keyword and country. Get copy, CTAs, landing URLs, platforms, and Ad Library IDs. Optional bring-your-own Facebook session cookies. No login automation. AI/MCP: search “Facebook Ads Scraper with Cookies”.

- **URL**: https://apify.com/masoncode/facebook-ads-scraper-with-cookies.md
- **Developed by:** [Mason Alv](https://apify.com/masoncode) (community)
- **Security:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 60.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 unique ads

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

## Facebook Ads Library Scraper — keyword + country competitive intel

Monitor competitor ads on Meta by **keyword and country**. Pass a search term and ISO country code; optionally attach **your own Facebook session cookies** for logged-in visibility. Get structured ad copy, CTAs, landing links, platforms, and Ad Library IDs in a dataset you can pipe to Sheets, Airtable, or your own alerts.

### What you get

- **Ad copy & creative signals** — headline, body, caption, CTA text, display format
- **Advertiser context** — page name, page URL, publisher platforms (Facebook, Instagram, etc.)
- **Transparency links** — `adArchiveId` and direct Ad Library URL per ad
- **Geo-scoped search** — results match the country you choose (required input)
- **Optional logged-in session** — bring your own Meta cookies when public results are not enough

### Sample output

```json
{
  "adArchiveId": "1234567890123456",
  "pageName": "Example Brand",
  "pageUrl": "https://www.facebook.com/examplebrand",
  "title": "Summer sale — 30% off",
  "body": "Shop the collection before it ends.",
  "ctaText": "Shop now",
  "linkUrl": "https://example.com/sale",
  "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
  "startDate": 1735689600,
  "isActive": true,
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1234567890123456",
  "searchQuery": "skincare serum",
  "country": "US",
  "scrapedAt": "2026-09-21T12:00:00.000Z"
}
```

### Use cases

- **Agencies & brands** — track competitor messaging and offers in a specific market
- **Performance marketers** — spot new creatives and CTAs by keyword vertical
- **Researchers** — export public transparency ads for category analysis
- **Automation** — schedule runs per country/keyword and diff datasets over time
- **Logged-in sweeps** — paste your own session cookies when Meta shows more to authenticated users

### How this differs from `apify/facebook-ads-scraper`

| | **This Actor** | **apify/facebook-ads-scraper** |
|---|---|---|
| **Entry point** | Keyword + country (required) | Page URLs or full Ad Library URLs |
| **Focus** | Thin, fast competitive keyword sweeps | Deep page-level + optional enrichment |
| **Login** | Optional bring-your-own cookies | None |
| **Session cookies** | You paste your own Meta cookies (secret input) | Not supported |
| **Best for** | "What are competitors saying about X in country Y?" | Full advertiser libraries, EU reach, e-commerce enrichment |

### Input

| Field | Required | Description |
|-------|----------|-------------|
| `searchQuery` | Yes | Keyword or brand to search |
| `country` | Yes | 2-letter ISO code (e.g. `US`, `GB`, `ID`) — **no default** |
| `maxAds` | No | Stop after N unique ads |
| `cookies` | No | Your own Meta/Facebook cookies (secret textarea) — see below |

#### Bring your own session cookies (optional)

This Actor does **not** log you into Facebook, sell cookies, or automate password login. If you want a logged-in browser context, paste **your own** Meta cookies into the `cookies` input.

**Supported formats:**

1. **JSON array** — export from a browser extension or DevTools, e.g. `[{"name":"c_user","value":"...","domain":".facebook.com","path":"/"}]`
2. **Semicolon string** — `c_user=123; xs=abc; datr=xyz`

Cookies are applied with Playwright `context.addCookies()` before the Ads Library page opens. Cookie values are treated as secrets in the Apify Console (encrypted at rest) and are never logged by this Actor.

**Your responsibility:** only use cookies from accounts you control. Comply with Meta Terms of Service. We do not provide stolen cookies, credential stuffing, or login automation.

### Run locally

```bash
npm install
npx playwright install chromium
mkdir -p storage/key_value_stores/default
cat > storage/key_value_stores/default/INPUT.json <<'EOF'
{
  "searchQuery": "coffee",
  "country": "US",
  "maxAds": 10
}
EOF
apify run
```

### Deploy to your Apify account (private)

This Actor is **not** published to Apify Store. Owner deploy steps:

1. `apify login` (Owner account)
2. `apify push` from this repo
3. Run on Apify Console with `searchQuery` + `country`
4. Optional: add your own `cookies` in the secret textarea if needed
5. Optional: set PPE pricing in Console if you resell runs

### Technical notes

- **Stack:** Node.js 22, Apify SDK, Playwright (`apify/actor-node-playwright` Docker image)
- **Method:** Opens public `facebook.com/ads/library` search, intercepts `/api/graphql/` responses, scrolls for pagination
- **Cookies:** Optional user-supplied session via Playwright `context.addCookies()` — no defaults, never logged
- **No built-in login** — public library works without cookies; cookies are an optional extra
- Geo-partitioned results: always set `country` to the market you care about

# Actor input Schema

## `searchQuery` (type: `string`):

Keyword or brand to search in the public Meta Ad Library (e.g. competitor name, product category, campaign theme).

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

2-letter ISO country code for Ad Library geo targeting (e.g. US, GB, ID, SG). Required — there is no default country.

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

Optional cap on how many unique ads to collect. Leave empty to scrape until scrolling stops returning new ads.

## `cookies` (type: `string`):

Your own Meta/Facebook cookies as a JSON array or semicolon-separated string. Bring your own session — paste cookies from your own logged-in browser. We do not provide cookies, login automation, or stolen sessions. You are responsible for complying with Meta Terms of Service.

## Actor input object example

```json
{}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("masoncode/facebook-ads-scraper-with-cookies").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("masoncode/facebook-ads-scraper-with-cookies").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 '{}' |
apify call masoncode/facebook-ads-scraper-with-cookies --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,masoncode/facebook-ads-scraper-with-cookies"
        }
    }
}
```

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/0DQX1foE36pEyz4hJ/builds/H2tuL6sUjhP8bNIET/openapi.json