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

{
  "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

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

Fetch direct ad details

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

Political and issue ads

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

Country political-ad report

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

Resolve branded-content profiles

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

Monitor ads on a schedule

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

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.