Facebook Ad Library Byline & Advertiser Ad Finder: MCP config, n8n workflow and API

{
  "mode": "search",
  "searchTerms": [
    "coffee"
  ],
  "adActiveStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "sortBy": "relevance",
  "resultsPerSearch": 3,
  "maxItems": 3,
  "includeEuDetails": false,
  "rehostMedia": false,
  "onlyTotal": false
}

---
name: facebook-ad-library-byline-and-advertiser-ad
description: "One record per Facebook Ad Library ad: creative text, media, run dates, platform placements, creative reuse, advertiser context, and political/EU spend, impression and reach data where Meta publishes it. Fields the source does not provide for an ad are omitted. Runs the Apify Actor nimbryxo-studio/facebook-ad-library-byline-and-advertiser-ad. Use when the user needs Meta Ad Library data with fields such as ad_id, page_name, ad_text, start_date, status, media_type and an Apify token is available."
compatibility: "Needs network access, curl, and an APIFY_TOKEN environment variable. Runs are billed to the token owner's Apify account."
metadata:
  actor: "nimbryxo-studio/facebook-ad-library-byline-and-advertiser-ad"
  store-url: "https://apify.com/nimbryxo-studio/facebook-ad-library-byline-and-advertiser-ad"
---

# Facebook Ad Library Byline & Advertiser Ad Finder

Use this skill to fetch Meta Ad Library data with the Apify Actor `nimbryxo-studio/facebook-ad-library-byline-and-advertiser-ad` and work with the returned rows.

## Before running

1. Check that `APIFY_TOKEN` is set in the environment. Never print it or write it to a file.
2. Build `input.json` from the user's request using the fields below. Keep limits small for a first run.
3. Confirm the search terms or URLs with the user if the request is ambiguous.

## Input fields

| Field | Type | Meaning |
| --- | --- | --- |
| `mode` | one of `search`, `byPage`, `byAdId`, `byByline`, required | What to scrape. Leave empty to process every target list you filled in (searchTerms, pageIds, adIds, bylines) in one run. |
| `searchTerms` | array | Keywords to search for in the Ad Library, one search per term. Example: ["coffee", "nike"]. |
| `adActiveStatus` | one of `all`, `active`, `inactive` | Filter by ad active status. |
| `adType` | one of `all`, `political_and_issue_ads`, `housing`, `employment`, `credit` | Filter by ad category. Note: the political-and-issue archive excludes EU/EEA countries, so EU political searches automatically use All Types (EU transparency stream). |
| `mediaType` | one of `all`, `image`, `video`, `meme`, `none` | Filter by the ad's creative media type. `meme` is applied server-side only; Meta's payload has no meme marker, so output `media_type` is always image, video or none. |
| `searchType` | one of `keyword_unordered`, `keyword_exact_phrase` | How keyword search terms are matched (mode=search only). |
| `sortBy` | one of `relevance`, `total_impressions` | Order results by relevance (Facebook's default) or by total impressions. |
| `resultsPerSearch` | integer | Maximum number of ads to extract per search term / page / ad / byline. |
| `maxItems` | integer | Stop the whole run after this many ads, across all search targets. |
| `includeEuDetails` | boolean | Fetch per-ad detail data: EU total reach, age/country/gender reach breakdown, targeting, payer/beneficiary, advertiser Instagram profile and page About. Adds one extra request per ad. |
| `rehostMedia` | boolean | Copy each ad's primary media (up to 15 MB) into this run's key-value store and output the permanent URL (Facebook's own media URLs expire after a few days). |
| `onlyTotal` | boolean | Skip ad scraping and return one total per search target per country (one lightweight page request per country, no browser). Counts respect the keyword, country, status, ad type, media type and date window; Facebook caps displayed totals at 50,001 (50,000+). |

Example `input.json` (the Actor's published prefill):

```json
{
  "mode": "search",
  "searchTerms": [
    "coffee"
  ],
  "adActiveStatus": "active",
  "adType": "all",
  "mediaType": "all",
  "searchType": "keyword_unordered",
  "sortBy": "relevance",
  "resultsPerSearch": 3,
  "maxItems": 3,
  "includeEuDetails": false,
  "rehostMedia": false,
  "onlyTotal": false
}
```

## Run

```bash
curl -sS -X POST "https://api.apify.com/v2/acts/nimbryxo-studio~facebook-ad-library-byline-and-advertiser-ad/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json > results.json
```

The call waits for the run to finish and returns the dataset items as a JSON array. If the run needs more than 300 seconds the API answers with HTTP 408; then start the run with `POST /v2/acts/nimbryxo-studio~facebook-ad-library-byline-and-advertiser-ad/runs`, poll `GET /v2/actor-runs/{runId}` until `SUCCEEDED`, and read `GET /v2/datasets/{defaultDatasetId}/items`.

## Output

Each item is one record. Published fields include: `ad_id`, `page_name`, `ad_text`, `start_date`, `status`, `media_type`, `cta_text`, `link_url`, `publisher_platform`, `collation_count`, `spend`, `impressions`, `ad_snapshot_url`, `search_term`, `page_id`, `page_url`, `resolved_ad_text`, `template_tokens`, `title`, `caption`.

Summarise what was found, cite the record URLs when present, and say how many items came back. Do not invent values for empty fields.