# Facebook Ads Library Scraper - Reports & Monitor (`scrapingmonkey/facebook-ads-library-scraper`) Actor

Scrape public Facebook and Instagram ads by keyword, Page ID, or URL. Extract creatives and transparency data, analyze political-ad reports, resolve branded profiles, and monitor new, changed, stopped, or reactivated ads.

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

## Pricing

from $0.42 / 1,000 ad results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Scraper - Ads, Creatives, Transparency and Political Reports

Extract public Facebook and Instagram ads, complete creative variants, advertiser transparency, political spending reports, branded-profile matches, and scheduled changes from Meta Ads Library.

- Search by keyword, exact phrase, advertiser Page ID, or a current Ads Library URL
- Extract ad text, landing pages, image/video media, carousel cards, platforms, dates, and status
- Enrich ads with advertiser, audience, geographic, EU/UK/BR, payer, financial-services, and violation data when Meta publishes it
- Build country report tables with totals, ranked advertisers, regional spending, keywords, trackers, and snapshot availability
- Monitor new, changed, stopped, and reactivated ads with persistent scheduled-run state
- Process multiple queries, pages, countries, and direct ad IDs in one run
- No Facebook login, Meta API token, or user-supplied proxy is required; all requests use the built-in Apify Residential Proxy
- Export results to JSON, CSV, Excel, XML, RSS, or access them through the Apify API

### What can you do with this Actor?

| Mode | Input | Output | Best for |
| --- | --- | --- | --- |
| `search` | Keywords, Page IDs, or Ads Library URLs | Public ad records and complete creatives | Competitor research and creative discovery |
| `details` | Numeric archive IDs or direct ad URLs | One enriched record per public ad | Compliance, advertiser due diligence, and EU transparency |
| `political` | Keywords, Page IDs, countries, bylines, and regions | Political ads enriched with available spend, reach, audience, and regulatory data | Election, policy, and public-interest research |
| `report` | Country, report date, time range, advertiser filter | Overview, advertiser, location, and download-availability records | Political-spend rankings and country analysis |
| `brandedContent` | Creator or business names and platform | Matching public Facebook or Instagram profiles | Resolving entities before branded-content research |
| `monitor` | The same sources and filters as Search plus a monitor key | Only new, changed, stopped, or reactivated ads | Scheduled competitor and campaign alerts |

One mode runs at a time. Search and Political can enrich every ad with Details in the same run. All result types use the same stable 52-field top-level contract and appear in one **Results** table.

### Quick start

1. Open the Actor and click **Try for free**.
2. Keep **Search ads** selected and enter a brand, product, or advertiser name.
3. Choose countries and set **Maximum results per source**.
4. Click **Start**.
5. Preview the single Results table or download it in your preferred format.

The default input searches for `Nike` in the United States and is ready to run.

### Input examples

#### Search public ads

```json
{
  "mode": "search",
  "searchQueries": ["Nike", "running shoes"],
  "countries": ["US"],
  "activeStatus": "active",
  "maxResults": 50
}
```

`maxResults` applies independently to every query, Page ID, or search URL. One dataset row represents one deduplicated ad archive ID.

#### Search an advertiser page and fetch transparency details

```json
{
  "mode": "search",
  "pageIds": ["1347126975377308"],
  "countries": ["US", "GB"],
  "includeAdDetails": true,
  "maxResults": 100
}
```

#### Fetch direct ad details

```json
{
  "mode": "details",
  "adArchiveIds": [
    "27570265279288753",
    "https://www.facebook.com/ads/library/?id=123456789012345"
  ],
  "countries": ["US"]
}
```

#### Political and issue ads

```json
{
  "mode": "political",
  "searchQueries": ["healthcare policy"],
  "countries": ["US"],
  "activeStatus": "all",
  "bylines": [],
  "regions": [],
  "maxResults": 100
}
```

#### Country political-ad report

```json
{
  "mode": "report",
  "reportCountry": "US",
  "reportTimePreset": "LAST_30_DAYS",
  "reportSortColumn": "SPEND",
  "reportSortDescending": true,
  "maxResults": 100
}
```

#### Resolve branded-content profiles

```json
{
  "mode": "brandedContent",
  "searchQueries": ["Nike"],
  "brandedPlatform": "INSTAGRAM",
  "brandedStartDate": "2026-08-01",
  "brandedEndDate": "2026-08-11",
  "maxResults": 20
}
```

#### Monitor ads on a schedule

```json
{
  "mode": "monitor",
  "searchQueries": ["competitor brand"],
  "countries": ["US"],
  "monitorKey": "competitor-us-ads",
  "monitorBehavior": "newAndChanged",
  "maxResults": 500
}
```

### Complete output examples

Every runtime row contains exactly the same 52 top-level fields. Unavailable or unrelated values are represented by `null`, `[]`, `false`, or `0`; top-level keys are not omitted. `raw` is `null` unless `includeRaw` is enabled.

#### Complete `ad` output - 52 top-level fields

```json
{
  "recordType": "ad",
  "resultType": "ad",
  "id": "27570265279288753",
  "adArchiveId": "27570265279288753",
  "adId": "120219576487120654",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=27570265279288753",
  "pageId": "1347126975377308",
  "pageName": "Example Sports",
  "pageUrl": "https://www.facebook.com/1347126975377308",
  "isActive": true,
  "status": "active",
  "startDate": "2026-08-01T00:00:00Z",
  "endDate": null,
  "daysRunning": 10,
  "totalActiveSeconds": 864000,
  "platforms": ["FACEBOOK", "INSTAGRAM"],
  "categories": ["UNKNOWN"],
  "currency": "USD",
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": ["US"],
  "body": "Move every day in the new training collection.",
  "title": "Built for your next run",
  "caption": "EXAMPLE.COM",
  "description": "Shop the latest performance styles.",
  "ctaText": "Shop now",
  "ctaType": "SHOP_NOW",
  "destinationUrl": "https://example.com/running",
  "destinationDomain": "example.com",
  "displayFormat": "SINGLE_IMAGE",
  "media": [
    {
      "type": "image",
      "url": "https://scontent.example/ad-original.jpg",
      "thumbnailUrl": "https://scontent.example/ad-preview.jpg",
      "width": 1080,
      "height": 1080
    }
  ],
  "cards": [
    {
      "body": "Daily trainer",
      "title": "Road Runner 2",
      "caption": "EXAMPLE.COM",
      "description": "Responsive everyday cushioning.",
      "ctaText": "Shop now",
      "ctaType": "SHOP_NOW",
      "destinationUrl": "https://example.com/road-runner",
      "destinationDomain": "example.com",
      "media": [
        {
          "type": "image",
          "url": "https://scontent.example/card.jpg",
          "thumbnailUrl": "https://scontent.example/card-preview.jpg",
          "width": 1080,
          "height": 1080
        }
      ]
    }
  ],
  "creativeVariants": [
    {
      "index": 0,
      "text": "A second public creative variation.",
      "destinationUrl": "https://example.com/variant",
      "destinationDomain": "example.com",
      "media": [
        {
          "type": "video",
          "url": "https://video.example/variant.mp4",
          "thumbnailUrl": "https://video.example/variant.jpg",
          "width": 1080,
          "height": 1920
        }
      ]
    }
  ],
  "creativeVariantCount": 1,
  "mediaCount": 2,
  "collation": {"id": "701234567890", "count": 3},
  "containsDigitalCreatedMedia": false,
  "containsSensitiveContent": false,
  "stateMediaRunLabel": null,
  "adMetadata": {
    "fevInfo": null,
    "gatedType": null,
    "hideDataStatus": null,
    "reportCount": 0,
    "isAaaEligible": true,
    "pageIsDeleted": false,
    "hasUserReported": false,
    "menuItems": []
  },
  "creativeMetadata": {
    "additionalInfo": null,
    "event": null,
    "brandedContent": null,
    "rootResharedPost": null,
    "isReshared": false,
    "disclaimerLabel": null,
    "byline": null,
    "pageLikeCount": 125000,
    "pageCategories": ["Sportswear Store"],
    "countryIsoCode": "US",
    "brazilTaxId": null,
    "ecCertificates": [],
    "pageProfilePictureUrl": "https://scontent.example/page.jpg"
  },
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": null,
  "brandedContent": null,
  "source": {
    "mode": "search",
    "query": "running shoes",
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/?country=US&q=running+shoes",
    "rank": 1,
    "reportDate": null,
    "timePreset": null
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:00:00Z",
  "raw": null
}
```

#### Complete `adDetail` output - 52 top-level fields

```json
{
  "recordType": "ad",
  "resultType": "adDetail",
  "id": "27570265279288753",
  "adArchiveId": "27570265279288753",
  "adId": "120219576487120654",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=27570265279288753",
  "pageId": "208685479508187",
  "pageName": "Example Public Campaign",
  "pageUrl": "https://www.facebook.com/208685479508187",
  "isActive": false,
  "status": "inactive",
  "startDate": "2026-07-01T00:00:00Z",
  "endDate": "2026-07-31T00:00:00Z",
  "daysRunning": 30,
  "totalActiveSeconds": 2592000,
  "platforms": ["FACEBOOK", "INSTAGRAM"],
  "categories": ["POLITICAL_AND_ISSUE_ADS"],
  "currency": "USD",
  "spend": {"lowerBound": 1000, "upperBound": 1499, "index": null, "text": null},
  "impressions": {"lowerBound": 100000, "upperBound": 124999, "index": 8, "text": null},
  "reachEstimate": {"lowerBound": 90000, "upperBound": 110000, "index": null, "text": null},
  "targetedCountries": ["US"],
  "body": "A public issue-ad message.",
  "title": "Learn about the proposal",
  "caption": "EXAMPLE.ORG",
  "description": "Read the public policy summary.",
  "ctaText": "Learn more",
  "ctaType": "LEARN_MORE",
  "destinationUrl": "https://example.org/proposal",
  "destinationDomain": "example.org",
  "displayFormat": "VIDEO",
  "media": [
    {
      "type": "video",
      "url": "https://video.example/policy.mp4",
      "thumbnailUrl": "https://video.example/policy.jpg",
      "width": 1920,
      "height": 1080
    }
  ],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 1,
  "mediaCount": 1,
  "collation": {"id": null, "count": 1},
  "containsDigitalCreatedMedia": false,
  "containsSensitiveContent": false,
  "stateMediaRunLabel": null,
  "adMetadata": {
    "fevInfo": null,
    "gatedType": null,
    "hideDataStatus": null,
    "reportCount": 0,
    "isAaaEligible": false,
    "pageIsDeleted": false,
    "hasUserReported": false,
    "menuItems": []
  },
  "creativeMetadata": {
    "additionalInfo": null,
    "event": null,
    "brandedContent": null,
    "rootResharedPost": null,
    "isReshared": false,
    "disclaimerLabel": "Paid for by Example Committee",
    "byline": "Example Committee",
    "pageLikeCount": 5300,
    "pageCategories": ["Political Organization"],
    "countryIsoCode": "US",
    "brazilTaxId": null,
    "ecCertificates": [],
    "pageProfilePictureUrl": "https://scontent.example/committee.jpg"
  },
  "regionalRegulationData": {"regions": ["US"]},
  "advertiser": {"page_id": "208685479508187", "page_name": "Example Public Campaign", "page_spend": 24500},
  "transparency": {
    "insights": {"age_gender": [{"age_range": "25-34", "female": 0.51, "male": 0.47, "unknown": 0.02}]},
    "transparencyByLocation": {
      "br_transparency": null,
      "eu_transparency": {"targets_eu": true, "eu_total_reach": 25000, "age_audience": {"min": 18, "max": 65}, "gender_audience": "ALL", "location_audience": [{"name": "Germany", "type": "COUNTRY", "excluded": false, "num_obfuscated": 25000}]},
      "uk_transparency": null
    },
    "verifiedVoiceContext": {"types": [], "ad_library_all_geo_fin_serv_info": {"finserv_data": []}},
    "violationTypes": [{"name": "Example policy notice", "link": "https://example.org/policy", "is_legal": true}],
    "isViolatingEuSiep": false,
    "eligibleForAiDisclosure": true
  },
  "report": null,
  "brandedContent": null,
  "source": {
    "mode": "details",
    "query": null,
    "pageId": "208685479508187",
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/?id=27570265279288753&country=US",
    "rank": null,
    "reportDate": null,
    "timePreset": null
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:01:00Z",
  "raw": null
}
```

#### Complete `reportOverview` output - 52 top-level fields

```json
{
  "recordType": "report",
  "resultType": "reportOverview",
  "id": "report-overview-US-2026-08-11-LAST_30_DAYS",
  "adArchiveId": null,
  "adId": null,
  "adLibraryUrl": null,
  "pageId": null,
  "pageName": null,
  "pageUrl": null,
  "isActive": null,
  "status": null,
  "startDate": null,
  "endDate": null,
  "daysRunning": null,
  "totalActiveSeconds": null,
  "platforms": [],
  "categories": [],
  "currency": null,
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": [],
  "body": null,
  "title": null,
  "caption": null,
  "description": null,
  "ctaText": null,
  "ctaType": null,
  "destinationUrl": null,
  "destinationDomain": null,
  "displayFormat": null,
  "media": [],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 0,
  "mediaCount": 0,
  "collation": null,
  "containsDigitalCreatedMedia": null,
  "containsSensitiveContent": null,
  "stateMediaRunLabel": null,
  "adMetadata": null,
  "creativeMetadata": null,
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": {
    "country": "US",
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS",
    "totalAds": 24500,
    "totalSpend": 12500000,
    "keywords": ["healthcare", "jobs", "election"],
    "spendTrackerData": [{"page_id": "208685479508187", "spend": 24500}],
    "spendTrackerTypeahead": [{"page_id": "208685479508187", "page_name": "Example Public Campaign"}],
    "advertiser": null,
    "location": null,
    "availableDownloads": [],
    "supportedCountries": [],
    "hasNextPage": false,
    "endCursor": null
  },
  "brandedContent": null,
  "source": {
    "mode": "report",
    "query": null,
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/report/",
    "rank": null,
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS"
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:02:00Z",
  "raw": null
}
```

#### Complete `reportAdvertiser` output - 52 top-level fields

```json
{
  "recordType": "report",
  "resultType": "reportAdvertiser",
  "id": "report-advertiser-US-208685479508187",
  "adArchiveId": null,
  "adId": null,
  "adLibraryUrl": null,
  "pageId": "208685479508187",
  "pageName": "Example Public Campaign",
  "pageUrl": "https://www.facebook.com/208685479508187",
  "isActive": null,
  "status": null,
  "startDate": null,
  "endDate": null,
  "daysRunning": null,
  "totalActiveSeconds": null,
  "platforms": [],
  "categories": [],
  "currency": "USD",
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": [],
  "body": null,
  "title": null,
  "caption": null,
  "description": null,
  "ctaText": null,
  "ctaType": null,
  "destinationUrl": null,
  "destinationDomain": null,
  "displayFormat": null,
  "media": [],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 0,
  "mediaCount": 0,
  "collation": null,
  "containsDigitalCreatedMedia": null,
  "containsSensitiveContent": null,
  "stateMediaRunLabel": null,
  "adMetadata": null,
  "creativeMetadata": null,
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": {
    "country": "US",
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS",
    "totalAds": 312,
    "totalSpend": 245000,
    "keywords": [],
    "spendTrackerData": [],
    "spendTrackerTypeahead": [],
    "advertiser": {
      "rank": 1,
      "id": "1073538731696428",
      "pageId": "208685479508187",
      "name": "Example Public Campaign",
      "iconUrl": "https://scontent.example/campaign.jpg",
      "disclaimer": "Paid for by Example Committee",
      "detailedSpends": [{"amount": 245000, "currency": "USD"}],
      "showDetailedSpends": true,
      "isDeleted": false
    },
    "location": null,
    "availableDownloads": [],
    "supportedCountries": [],
    "hasNextPage": true,
    "endCursor": "AQHS-example-cursor"
  },
  "brandedContent": null,
  "source": {
    "mode": "report",
    "query": null,
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/report/",
    "rank": null,
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS"
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:02:01Z",
  "raw": null
}
```

#### Complete `reportLocation` output - 52 top-level fields

```json
{
  "recordType": "report",
  "resultType": "reportLocation",
  "id": "report-location-US-California",
  "adArchiveId": null,
  "adId": null,
  "adLibraryUrl": null,
  "pageId": null,
  "pageName": null,
  "pageUrl": null,
  "isActive": null,
  "status": null,
  "startDate": null,
  "endDate": null,
  "daysRunning": null,
  "totalActiveSeconds": null,
  "platforms": [],
  "categories": [],
  "currency": "USD",
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": [],
  "body": null,
  "title": null,
  "caption": null,
  "description": null,
  "ctaText": null,
  "ctaType": null,
  "destinationUrl": null,
  "destinationDomain": null,
  "displayFormat": null,
  "media": [],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 0,
  "mediaCount": 0,
  "collation": null,
  "containsDigitalCreatedMedia": null,
  "containsSensitiveContent": null,
  "stateMediaRunLabel": null,
  "adMetadata": null,
  "creativeMetadata": null,
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": {
    "country": "US",
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS",
    "totalAds": null,
    "totalSpend": 875000,
    "keywords": [],
    "spendTrackerData": [],
    "spendTrackerTypeahead": [],
    "advertiser": null,
    "location": {
      "rank": 1,
      "name": "California",
      "detailedSpends": [{"amount": 875000, "currency": "USD"}],
      "showDetailedSpends": true
    },
    "availableDownloads": [],
    "supportedCountries": [],
    "hasNextPage": false,
    "endCursor": null
  },
  "brandedContent": null,
  "source": {
    "mode": "report",
    "query": null,
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/report/",
    "rank": null,
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS"
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:02:02Z",
  "raw": null
}
```

#### Complete `reportDownload` output - 52 top-level fields

```json
{
  "recordType": "report",
  "resultType": "reportDownload",
  "id": "report-download-US-2026-08-11",
  "adArchiveId": null,
  "adId": null,
  "adLibraryUrl": null,
  "pageId": null,
  "pageName": null,
  "pageUrl": null,
  "isActive": null,
  "status": null,
  "startDate": null,
  "endDate": null,
  "daysRunning": null,
  "totalActiveSeconds": null,
  "platforms": [],
  "categories": [],
  "currency": null,
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": [],
  "body": null,
  "title": null,
  "caption": null,
  "description": null,
  "ctaText": null,
  "ctaType": null,
  "destinationUrl": null,
  "destinationDomain": null,
  "displayFormat": null,
  "media": [],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 0,
  "mediaCount": 0,
  "collation": null,
  "containsDigitalCreatedMedia": null,
  "containsSensitiveContent": null,
  "stateMediaRunLabel": null,
  "adMetadata": null,
  "creativeMetadata": null,
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": {
    "country": "US",
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS",
    "totalAds": null,
    "totalSpend": null,
    "keywords": [],
    "spendTrackerData": [],
    "spendTrackerTypeahead": [],
    "advertiser": null,
    "location": null,
    "availableDownloads": [
      {
        "key": "2026-08-10",
        "value": [
          {"available": true, "query_time": "YESTERDAY"},
          {"available": true, "query_time": "LAST_30_DAYS"}
        ]
      }
    ],
    "supportedCountries": ["ALL", "US", "GB", "DE"],
    "hasNextPage": false,
    "endCursor": null
  },
  "brandedContent": null,
  "source": {
    "mode": "report",
    "query": null,
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/report/",
    "rank": null,
    "reportDate": "2026-08-11",
    "timePreset": "LAST_30_DAYS"
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:02:03Z",
  "raw": null
}
```

#### Complete `brandedProfile` output - 52 top-level fields

```json
{
  "recordType": "brandedContent",
  "resultType": "brandedProfile",
  "id": "branded-profile-17841400602400210",
  "adArchiveId": null,
  "adId": null,
  "adLibraryUrl": null,
  "pageId": "17841400602400210",
  "pageName": "Nike",
  "pageUrl": "https://www.instagram.com/nike/",
  "isActive": null,
  "status": null,
  "startDate": null,
  "endDate": null,
  "daysRunning": null,
  "totalActiveSeconds": null,
  "platforms": [],
  "categories": [],
  "currency": null,
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": [],
  "body": null,
  "title": null,
  "caption": null,
  "description": null,
  "ctaText": null,
  "ctaType": null,
  "destinationUrl": null,
  "destinationDomain": null,
  "displayFormat": null,
  "media": [],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 0,
  "mediaCount": 0,
  "collation": null,
  "containsDigitalCreatedMedia": null,
  "containsSensitiveContent": null,
  "stateMediaRunLabel": null,
  "adMetadata": null,
  "creativeMetadata": null,
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": null,
  "brandedContent": {
    "rank": 1,
    "platform": "INSTAGRAM",
    "entityId": "17841400602400210",
    "name": "Nike",
    "handle": "nike",
    "followers": 300000000,
    "isVerified": true,
    "profilePictureUrl": "https://scontent.example/nike.jpg",
    "creator": null,
    "brandPartner": null,
    "contentType": null,
    "publishedAt": null,
    "postUrl": null,
    "mediaUrl": null
  },
  "source": {
    "mode": "brandedContent",
    "query": "Nike",
    "pageId": "17841400602400210",
    "countries": [],
    "sourceUrl": "https://www.facebook.com/ads/library/branded_content/?id=17841400602400210&query=Nike&target=instagram",
    "rank": 1,
    "reportDate": null,
    "timePreset": null
  },
  "monitorStatus": null,
  "changedFields": [],
  "scrapedAt": "2026-08-11T08:03:00Z",
  "raw": null
}
```

#### Complete `adChange` output - 52 top-level fields

```json
{
  "recordType": "ad",
  "resultType": "adChange",
  "id": "27570265279288753",
  "adArchiveId": "27570265279288753",
  "adId": "120219576487120654",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=27570265279288753",
  "pageId": "1347126975377308",
  "pageName": "Example Sports",
  "pageUrl": "https://www.facebook.com/1347126975377308",
  "isActive": false,
  "status": "inactive",
  "startDate": "2026-08-01T00:00:00Z",
  "endDate": "2026-08-11T07:55:00Z",
  "daysRunning": 10,
  "totalActiveSeconds": 860100,
  "platforms": ["FACEBOOK", "INSTAGRAM"],
  "categories": ["UNKNOWN"],
  "currency": "USD",
  "spend": null,
  "impressions": null,
  "reachEstimate": null,
  "targetedCountries": ["US"],
  "body": "Move every day in the updated training collection.",
  "title": "Built for your next run",
  "caption": "EXAMPLE.COM",
  "description": "Shop the latest performance styles.",
  "ctaText": "Shop now",
  "ctaType": "SHOP_NOW",
  "destinationUrl": "https://example.com/running",
  "destinationDomain": "example.com",
  "displayFormat": "SINGLE_IMAGE",
  "media": [
    {
      "type": "image",
      "url": "https://scontent.example/ad-updated.jpg",
      "thumbnailUrl": "https://scontent.example/ad-updated-preview.jpg",
      "width": 1080,
      "height": 1080
    }
  ],
  "cards": [],
  "creativeVariants": [],
  "creativeVariantCount": 1,
  "mediaCount": 1,
  "collation": {"id": "701234567890", "count": 3},
  "containsDigitalCreatedMedia": false,
  "containsSensitiveContent": false,
  "stateMediaRunLabel": null,
  "adMetadata": {
    "fevInfo": null,
    "gatedType": null,
    "hideDataStatus": null,
    "reportCount": 0,
    "isAaaEligible": true,
    "pageIsDeleted": false,
    "hasUserReported": false,
    "menuItems": []
  },
  "creativeMetadata": {
    "additionalInfo": null,
    "event": null,
    "brandedContent": null,
    "rootResharedPost": null,
    "isReshared": false,
    "disclaimerLabel": null,
    "byline": null,
    "pageLikeCount": 125100,
    "pageCategories": ["Sportswear Store"],
    "countryIsoCode": "US",
    "brazilTaxId": null,
    "ecCertificates": [],
    "pageProfilePictureUrl": "https://scontent.example/page.jpg"
  },
  "regionalRegulationData": null,
  "advertiser": null,
  "transparency": null,
  "report": null,
  "brandedContent": null,
  "source": {
    "mode": "monitor",
    "query": "Example Sports",
    "pageId": null,
    "countries": ["US"],
    "sourceUrl": "https://www.facebook.com/ads/library/?country=US&q=Example+Sports",
    "rank": 1,
    "reportDate": null,
    "timePreset": null
  },
  "monitorStatus": "stopped",
  "changedFields": ["isActive", "status", "endDate", "body", "media"],
  "scrapedAt": "2026-08-11T08:04:00Z",
  "raw": null
}
```

### What data can you extract?

| Category | Complete field inventory |
| --- | --- |
| Row identity | `recordType`, `resultType`, `id` |
| Ad and advertiser identity | `adArchiveId`, `adId`, `adLibraryUrl`, `pageId`, `pageName`, `pageUrl` |
| Lifecycle | `isActive`, `status`, `startDate`, `endDate`, `daysRunning`, `totalActiveSeconds` |
| Distribution | `platforms`, `categories`, `targetedCountries` |
| Spend and delivery | `currency`, `spend`, `impressions`, `reachEstimate` |
| Creative | `body`, `title`, `caption`, `description`, `ctaText`, `ctaType`, `destinationUrl`, `destinationDomain`, `displayFormat` |
| Media and variants | `media`, `cards`, `creativeVariants`, `creativeVariantCount`, `mediaCount`, `collation` |
| Safety and metadata | `containsDigitalCreatedMedia`, `containsSensitiveContent`, `stateMediaRunLabel`, `adMetadata`, `creativeMetadata` |
| Regulation and details | `regionalRegulationData`, `advertiser`, `transparency` |
| Specialized workflows | `report`, `brandedContent` |
| Provenance and monitoring | `source`, `monitorStatus`, `changedFields`, `scrapedAt`, `raw` |

Nested ad metadata preserves FEV data, gated/hide status, report count, AAA eligibility, deleted-page status, user-report state, and menu items. Creative metadata preserves additional information, events, branded-content metadata, reshared posts, disclaimer/byline, page likes/categories, country, Brazil tax ID, EC certificates, and profile image. Transparency preserves insights, regional tables, verified-voice and financial-services data, violations, EU SIEP state, and AI-disclosure eligibility.

### Input parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mode` | string | Yes | `search` | `search`, `details`, `political`, `report`, `brandedContent`, or `monitor` |
| `searchQueries` | string\[] | Search/Political/Branded/Monitor | `['Nike']` | Keywords, exact phrases, creator names, or businesses; limit is per query |
| `pageIds` | string\[] | No | `[]` | Numeric Facebook Page IDs, each used as an independent ad source |
| `pageUrls` | string\[] | No | `[]` | Current Ads Library advertiser/search URLs |
| `adArchiveIds` | string\[] | Details | `[]` | Numeric archive IDs or direct Ads Library URLs containing `?id=` |
| `startUrls` | string\[] | No | `[]` | Mixed public Ads Library search, advertiser, or direct-ad URLs |
| `countries` | string\[] | No | `['US']` | ISO alpha-2 countries or `ALL` |
| `language` | string | No | `en-US` | Facebook request locale |
| `adType` | string | No | `ALL` | All, political/issues, housing, employment, credit, or financial-services ads |
| `activeStatus` | string | No | `all` | `all`, `active`, or `inactive` |
| `searchType` | string | No | `keyword_unordered` | Unordered keywords, exact phrase, or page matching |
| `mediaType` | string | No | `all` | All, image, meme, image+memes, video, or no image/video |
| `publisherPlatforms` | string\[] | No | `[]` | Facebook, Instagram, Audience Network, Messenger, WhatsApp, or Threads |
| `contentLanguages` | string\[] | No | `[]` | Meta ad-content language filters |
| `bylines` | string\[] | No | `[]` | Political-ad disclaimer/byline filters |
| `regions` | string\[] | No | `[]` | Meta delivery-region filter values |
| `dateFrom` | string | No | - | Minimum start date, `YYYY-MM-DD` |
| `dateTo` | string | No | - | Maximum start date, `YYYY-MM-DD` |
| `sortMode` | string | No | `none` | Meta order, impressions, reach, or recent |
| `sortDirection` | string | No | `desc` | `desc` or `asc` |
| `maxResults` | integer | No | `50` | Maximum ads per source, report advertisers, or profiles per query; 1-5,000 |
| `maxItems` | integer | No | `0` | Global deduplicated row limit; 0 disables the Actor-level limit |
| `includeAdDetails` | boolean | No | `false` | Enrich every search result with public transparency details |
| `includeRaw` | boolean | No | `false` | Preserve complete Meta source objects under `raw` |
| `maxConcurrency` | integer | No | `3` | Parallel independent sources/details; 1-10 |
| `maxRequestRetries` | integer | No | `5` | Retry and proxy-rotation attempts; 1-10 |
| `reportCountry` | string | Report | `US` | Country used by Ad Library Report |
| `reportDate` | string | No | Run date | Report snapshot date, `YYYY-MM-DD` |
| `reportTimePreset` | string | No | `LAST_30_DAYS` | Yesterday, 7, 30, 90 days, or lifetime |
| `reportQuery` | string | No | `''` | Optional advertiser-name filter |
| `reportSortColumn` | string | No | `SPEND` | Rank by `SPEND` or `ADS` |
| `reportSortDescending` | boolean | No | `true` | Highest report values first |
| `trackedPageIds` | string\[] | No | `[]` | Page IDs for the report spend tracker |
| `includeReportDownloads` | boolean | No | `true` | Add report-snapshot availability and supported countries |
| `brandedPlatform` | string | Branded | `INSTAGRAM` | `INSTAGRAM` or `FACEBOOK` |
| `brandedStartDate` | string | No | - | Selected profile-page start date, `YYYY-MM-DD` |
| `brandedEndDate` | string | No | - | Selected profile-page end date, `YYYY-MM-DD` |
| `monitorKey` | string | Monitor | `facebook-ads-monitor` | Stable persistent monitor identity |
| `monitorBehavior` | string | No | `newAndChanged` | New only, or new+changed+stopped+reactivated |

### Use cases

#### Competitor creative intelligence

Search competitor names and product terms, compare copy, CTAs, formats, landing domains, carousel cards, and creative variants, then schedule recurring exports.

#### Political and public-interest research

Combine Political mode with Report mode to study public messages, disclaimers, estimated delivery, advertiser spending, geographic distribution, and country-level rankings.

#### Compliance and advertiser due diligence

Use Details mode for public advertiser, payer/beneficiary, EU/UK/BR targeting, verified-voice, financial-services, and policy-violation fields when Meta publishes them.

#### Campaign monitoring

Run Monitor mode from an Apify schedule. Every stable `monitorKey` keeps independent state and emits meaningful new, changed, stopped, and reactivated records for webhooks or downstream alerts.

#### Lead and landing-page research

Export advertiser names, Page IDs, destination domains, creative messages, and active dates to enrich CRM, market-research, or agency prospecting workflows.

### Performance and cost

This Actor uses pay-per-event billing. Check the Actor's **Pricing** tab for the current price of each event:

| Event | When it is charged |
| --- | --- |
| `ad-result` | One stored non-enriched public ad |
| `ad-detail` | One stored ad with the detail/transparency request completed |
| `report-record` | One stored overview, advertiser, location, or download-availability report row |
| `branded-content` | One stored matched branded-profile row |
| `ad-change` | One stored new, changed, stopped, or reactivated monitor row |

No event is charged for a failed request, a retry, a duplicate discarded before storage, or a zero-result source. Detail enrichment increases requests and runtime. Report mode makes several section requests, and `includeRaw` increases dataset storage. `maxConcurrency=2` or `3` is a practical starting point for stability; measured run times and costs depend on Meta response speed, filters, countries, and result volume.

### API usage

Replace `YOUR_USERNAME` with the published Actor owner name:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/YOUR_USERNAME~facebook-ads-library-scraper/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "search",
    "searchQueries": ["running shoes"],
    "countries": ["US"],
    "maxResults": 25
  }'
```

Use the dataset with Google Sheets, Make, Zapier, n8n, Airbyte, webhooks, Slack, an Apify schedule, or your data warehouse.

### Best for / not for

**Best for:** public ad discovery, competitor research, complete creative extraction, political-ad analytics, public regulatory transparency, advertiser rankings, and scheduled change detection.

**Not for:** private profiles, account-only data, personal targeting identities, ad creation or modification, CAPTCHA solving, private Meta API access, or guaranteed historical coverage beyond what Meta currently publishes.

### Limits and good to know

- One mode runs per Actor run; Search/Political can include Details enrichment.
- `maxResults` is per independent query, Page ID, or search URL; `maxItems` is global after deduplication.
- Meta decides which countries, historical ads, spend ranges, audience fields, media URLs, and regulatory details are publicly available.
- Branded Content mode currently resolves the public creator/business profiles exposed by Meta's logged-out typeahead and selected profile page; it does not claim account-only partnership posts.
- Report dates and downloadable snapshots can lag behind the current date and differ by country.
- Media URLs are source URLs and can expire; download them promptly if your workflow needs durable copies.
- The Actor retries temporary rate limits, blocked proxy sessions, timeouts, server failures, and stale persisted-query IDs. Independent failed sources do not erase successful results.
- Current persisted-query IDs and anonymous bootstrap fields are discovered at runtime; captured tokens, cookies, or user credentials are not embedded.
- The production Actor always uses Apify Residential Proxy. There is no proxy field in the public input.

### Frequently asked questions

#### Do I need a Facebook account or Meta API token?

No. The Actor uses only public, logged-out Ads Library pages. Meta may still limit availability by country, ad category, or source state.

#### Can I search several brands and countries in one run?

Yes. Add up to 100 queries/Page IDs/URLs. `maxResults` applies to each independent source before global deduplication and `maxItems`.

#### Why are spend, impressions, audience, or transparency fields empty?

Meta publishes those fields mainly for regulated or region-specific ads. Normal commercial ads often expose complete creatives and status but no spend or audience range.

#### Does the Actor keep every carousel and dynamic creative?

Yes. It preserves top-level media, carousel cards, and extra text/link/media variants instead of returning only the first visible creative.

#### Can I monitor ads continuously?

Use Monitor mode with the same `monitorKey` on an Apify schedule. The Actor compares stable ad snapshots and emits new, changed, stopped, or reactivated ads according to `monitorBehavior`.

#### Why did a run return fewer results than the limit?

The limit is a maximum. Meta can return fewer public matches, end pagination, remove ads, restrict a category, or temporarily rate-limit a source. Duplicate archive IDs are stored once.

#### Do I need to configure a proxy?

No. Apify Residential Proxy is mandatory and configured internally for every production request.

### Responsible use

This Actor extracts publicly available Ads Library information. Users are responsible for complying with applicable laws, privacy and election regulations, contractual obligations, and Meta's terms. Do not use the output to infer sensitive personal attributes or target individuals.

Facebook, Instagram, Meta, and Ads Library are trademarks of Meta Platforms, Inc. This Actor is independent and is not affiliated with, endorsed by, or sponsored by Meta.

### Support

If you encounter a problem, create an issue in the Actor's **Issues** tab. Include the run ID, mode, country, and a non-sensitive reproducible query, Page ID, or public ad archive ID. Never include proxy credentials, cookies, or private account data.

# Actor input Schema

## `mode` (type: `string`):

Search ads, fetch direct ad details, force political transparency, build country report tables, resolve branded profiles, or monitor ads on a schedule.

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

Keywords or exact phrases for Search, Political, Branded content, and Monitor modes.

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

Numeric Facebook Page IDs. Each page becomes an independent ad search source.

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

Facebook Ads Library URLs containing view\_all\_page\_id or other native filters.

## `adArchiveIds` (type: `array`):

Numeric ad archive IDs or direct Facebook Ads Library URLs containing ?id=. Required in Details mode.

## `startUrls` (type: `array`):

Optional mixed Ads Library search, advertiser, or direct ad URLs. Existing native URL filters are retained.

## `countries` (type: `array`):

Two-letter country codes such as US, GB, DE, or ALL. One search can target multiple countries.

## `language` (type: `string`):

Request locale such as en-US, de, fr-FR, or pt-BR.

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

Search all ads or a regulated Ads Library category. Political mode always uses political and issue ads.

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

Return all, currently active, or inactive ads.

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

Unordered keywords or exact phrase matching. Page-ID searches automatically use page matching.

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

Filter by image, meme, image or meme, video, or ads without image/video.

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

Any of FACEBOOK, INSTAGRAM, AUDIENCE\_NETWORK, MESSENGER, WHATSAPP, or THREADS.

## `contentLanguages` (type: `array`):

Meta language filter values. Leave empty for every content language.

## `bylines` (type: `array`):

Political-ad disclaimer/byline filters.

## `regions` (type: `array`):

Optional Meta delivery-region filter values, mainly useful for political ads.

## `dateFrom` (type: `string`):

Minimum ad start date in YYYY-MM-DD format.

## `dateTo` (type: `string`):

Maximum ad start date in YYYY-MM-DD format.

## `sortMode` (type: `string`):

Use Meta's natural order or sort supported searches by impressions, reach, or recency.

## `sortDirection` (type: `string`):

Descending or ascending when a sort metric is selected.

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

Maximum ads per query/page, report advertisers, or branded profiles per query.

## `maxItems` (type: `integer`):

Maximum deduplicated dataset rows for the whole run. Use 0 for no Actor-level global limit.

## `includeAdDetails` (type: `boolean`):

Open each discovered ad and add advertiser, audience, geographic, EU/UK/BR, payer, and violation data when Meta provides it.

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

Keep Meta's complete source objects inside raw in addition to normalized fields. This increases dataset size.

## `maxConcurrency` (type: `integer`):

Independent sources and ad detail pages processed in parallel. Conservative values reduce Meta rate limits.

## `maxRequestRetries` (type: `integer`):

Retries for temporary blocks, rate limits, proxy failures, stale persisted queries, and server errors. Proxy sessions rotate between attempts.

## `reportCountry` (type: `string`):

Two-letter country for Ad Library Report totals, advertisers, and locations.

## `reportDate` (type: `string`):

Report date in YYYY-MM-DD. Defaults to the run date.

## `reportTimePreset` (type: `string`):

Political-ad report aggregation window.

## `reportQuery` (type: `string`):

Optional text filter for the report advertiser ranking.

## `reportSortColumn` (type: `string`):

Rank report advertisers by spend or ad count.

## `reportSortDescending` (type: `boolean`):

Sort report advertisers from highest to lowest.

## `trackedPageIds` (type: `array`):

Optional advertiser Page IDs for the report spend tracker chart.

## `includeReportDownloads` (type: `boolean`):

Add a row describing available official report snapshots and supported countries.

## `brandedPlatform` (type: `string`):

Resolve public creator or business profiles on Instagram or Facebook.

## `brandedStartDate` (type: `string`):

Selected branded-content page start date in YYYY-MM-DD.

## `brandedEndDate` (type: `string`):

Selected branded-content page end date in YYYY-MM-DD.

## `monitorKey` (type: `string`):

Stable name for persistent monitor state across scheduled runs.

## `monitorBehavior` (type: `string`):

Emit only new ads or all new, changed, stopped, and reactivated ads.

## Actor input object example

```json
{
  "mode": "search",
  "searchQueries": [
    "Nike"
  ],
  "countries": [
    "US"
  ],
  "language": "en-US",
  "adType": "ALL",
  "activeStatus": "all",
  "searchType": "keyword_unordered",
  "mediaType": "all",
  "sortMode": "none",
  "sortDirection": "desc",
  "maxResults": 50,
  "maxItems": 0,
  "includeAdDetails": false,
  "includeRaw": false,
  "maxConcurrency": 3,
  "maxRequestRetries": 5,
  "reportCountry": "US",
  "reportTimePreset": "LAST_30_DAYS",
  "reportSortColumn": "SPEND",
  "reportSortDescending": true,
  "includeReportDownloads": true,
  "brandedPlatform": "INSTAGRAM",
  "monitorKey": "facebook-ads-monitor",
  "monitorBehavior": "newAndChanged"
}
```

# Actor output Schema

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

Complete ads, transparency details, political report rows, branded profiles, and monitored changes in one Results table.

# 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("scrapingmonkey/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 = {}

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

```

## MCP server setup

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