Facebook Ads Library Scraper

Facebook Ads Library Scraper

Facebook Ads Library Scraper is a production-ready Meta Ad Library scraper that collects public ad records from Facebook and Instagram, including creatives, copy, advertiser/page context, dates, regions, and spend/impressions (when available). It solves the pain of manual research by turning Ad Library pages and links into structured datasets you can plug into reports, dashboards, or analysis pipelines. Built for marketers, developers, analysts, and researchers, this Facebook ad library extractor scales from quick audits to bulk downloads with flexible inputs and proxy-aware reliability.

What data / output can you get?

Below are real output fields as they appear in the dataset. Values are normalized into a stable camelCase JSON shape for easy downstream use and export (CSV/JSON/Excel via Apify datasets).

Data type	Description	Example value
adArchiveID	Stable archive ID for the ad (camelCase)	"1573731810659177"
pageName	Advertiser page name	"Acme Co."
inputUrl	Source URL used to retrieve the ad	"https://www.facebook.com/ads/library/?active_status=all&country=US&..."
isActive	Whether the ad is active during the scrape window	true
startDateFormatted	ISO-like start date (UTC, formatted)	"2025-11-05T00:00:00.000Z"
endDateFormatted	ISO-like end date (UTC, formatted)	"2025-11-06T00:00:00.000Z"
currency	Ad currency code	"USD"
spend	Spend (when available)	150
publisherPlatform	Platforms where the ad ran	["FACEBOOK", "INSTAGRAM"]
impressionsWithIndex.impressionsText	Human-readable impressions text (when available)	"1K–2K"
snapshot.displayFormat	Inferred creative format from the snapshot	"IMAGE"
snapshot.linkUrl	Primary destination link (when available)	"https://example.com"
targetedOrReachedCountries	Countries targeted or reached	["US", "CA"]
regionalRegulationData	Regional compliance flags	{ "finserv": { "isDeemedFinserv": false } }

Bonus outputs:

• Full creative snapshot with images/videos, call-to-action, captions, and page metadata under snapshot
• Optional aboutPage snippets for page sources when includeAboutPage is enabled
• Count-only mode (onlyTotal) for quick totals per source

Exports are available in JSON, CSV, or Excel directly from the Apify dataset.

Key features

• ✨ Enriched per-ad details (toggle): Turn on isDetailsPerAd to run an additional lookup for richer metadata per ad (more complete rows; slower runs).
• 🔢 Count-only summaries: Enable onlyTotal to output one summary row per source with totalAdsCount — perfect for fast audits or monitoring.
• 📌 Flexible sources: Use startUrls to add Facebook Page URLs or Facebook Ads Library links — mix and match in a single run.
• 🎯 Default filters: Control defaults for page-based sources with countryCode, activeStatus, and period; Ad Library links can carry their own query filters.
• 🔒 Residential proxy support: Configure proxyConfiguration to route via Apify residential proxy endpoints when needed for the most natural-looking traffic.
• 🎚️ Predictable volume caps: Keep runs scoped with resultsLimit (global cap across all sources) and per-source item limits via startUrls entries.
• 🧱 Robust session handling: Automatic document ID resolution and proxy fallback logic help you scrape Facebook Ads Library reliably at scale.

How to use Facebook Ads Library Scraper - step by step

1. Sign in to Apify and open the Facebook Ads Library Scraper actor.
2. Add your sources in startUrls:
   • Paste Facebook Page URLs (e.g., https://www.facebook.com/SHEINOFFICIAL).
   • Paste Ad Library links (e.g., https://www.facebook.com/ads/library/?active_status=active&country=ALL&...).
3. Set resultsLimit to cap how many ads you collect across all sources in the run.
4. (Optional) Enable onlyTotal for per-source totals, and includeAboutPage to attach public “about” snippets for page sources.
5. (Optional) Choose defaults for page sources: countryCode, activeStatus, and period (absolute date YYYY-MM-DD or relative like “7 days”).
6. (Optional) Turn on proxyConfiguration if you want residential-only routing for greater reliability.
7. Click Run. The actor will prepare a session, resolve required Ad Library doc IDs, page through results, and (optionally) fetch extra details per ad.
8. Download results from the Dataset tab as JSON, CSV, or Excel — or fetch them via the Apify API for automation.

Pro tip: Combine a Facebook page ads scraper input (page URLs) with Ad Library links to compare keyword searches against specific advertiser pages in one run.

Use cases

Use case name	Description
Marketing team + competitor ad tracking	Monitor live and historical ads from competitor pages; export pageName, adArchiveID, snapshot creatives, and publisherPlatform to dashboards.
Agency + creative benchmarking	Aggregate snapshot.displayFormat, captions, and linkUrl across markets to identify winning formats and CTAs for proposals.
Compliance + transparency monitoring	Use onlyTotal to track totalAdsCount by source, then enable isDetailsPerAd selectively to review sensitive ads with containsSensitiveContent.
Product analytics + campaign QA	Verify publisherPlatform and targetedOrReachedCountries to ensure correct placement and regional coverage.
Data engineering + API pipelines	Schedule runs and pull datasets programmatically to power internal reporting and warehousing.
Academic research + media studies	Export structured fields (e.g., spend, impressionsWithIndex, regionalRegulationData) for cross-country analyses.

Why choose Facebook Ads Library Scraper?

This Meta Ad Library scraper prioritizes precision, structure, and reliability for production workflows.

• 🔍 Structured, ready-to-analyze output: Stable camelCase schema with snapshot, publisherPlatform, and normalized date fields.
• ⚙️ Flexible modes: Switch between count-only summaries (onlyTotal) and enriched ad rows (isDetailsPerAd) to match your workflow.
• 🌐 Proxy-aware reliability: Optional residential proxy routing with fallback logic designed for resilient scraping.
• 🚀 Scales with control: Use resultsLimit and per-source item limits to keep runs fast and predictable.
• 🧩 Developer-friendly: Consistent JSON output for easy ingestion into BI tools, scripts, or data pipelines.
• 🛡️ Public-data focus: Collects from Meta’s public Ad Library — a safer alternative to brittle browser plugins and extensions.

Is it legal / ethical to use Facebook Ads Library Scraper?

Yes — when used responsibly. This actor collects publicly available data from Meta’s Ad Library and does not access private profiles or authenticated data.

Guidelines for compliant use:

• Scrape only public Ad Library endpoints and pages.
• Respect applicable regulations (e.g., GDPR/CCPA) and your organization’s data policies.
• Review Meta’s terms for acceptable use of public transparency data.
• Consult your legal team for edge cases and jurisdiction-specific requirements.

Input parameters & output format

Below is a real input example and a complete list of parameters.

Example JSON input

{
  "startUrls": [
    "https://www.facebook.com/SHEINOFFICIAL",
    "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&search_type=keyword_unordered&q=shoes"
  ],
  "resultsLimit": 25,
  "onlyTotal": false,
  "includeAboutPage": true,
  "isDetailsPerAd": true,
  "countryCode": "ALL",
  "period": "7 days",
  "activeStatus": "all",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Input parameters

• startUrls (array)

  • Description: Paste Facebook Page URLs or Ad Library links. One entry per line. You can paste plain URLs, or use objects with a url field (optional label, limit, or period per item).
  • Default: none (prefill examples shown in UI)
  • Required: no

• resultsLimit (integer)

  • Description: Upper bound on ads returned across all sources in this run (min 1, max 50000).
  • Default: 10
  • Required: no

• onlyTotal (boolean)

  • Description: Instead of one row per ad, output one summary row per source with a total count.
  • Default: false
  • Required: no

• includeAboutPage (boolean)

  • Description: For Facebook Page sources, attach lightweight public title/description text when available.
  • Default: false
  • Required: no

• isDetailsPerAd (boolean)

  • Description: Runs an additional lookup per ad for richer metadata (more complete rows; slower runs).
  • Default: true
  • Required: no

• countryCode (string; enum)

  • Description: Default region for Facebook Page sources when your URL doesn’t include one. Ad Library links usually carry their own country.
  • Default: "ALL"
  • Required: no

• period (string)

  • Description: Optional default time window. Leave empty to follow the library’s default. Accepts absolute date (YYYY-MM-DD) or relative spans like “7 days”.
  • Default: ""
  • Required: no

• activeStatus (string; enum: all, active, inactive)

  • Description: Default ad activity filter for Page sources, or when your Ad Library link leaves this unspecified.
  • Default: "all"
  • Required: no

• proxyConfiguration (object)

  • Description: Optional Apify Proxy. If enabled here, only residential proxy traffic is used for the whole run.
  • Default: { "useApifyProxy": false }
  • Required: no

Output format

Full ad row (isDetailsPerAd on or off; structure stays consistent)

{
  "inputUrl": "https://www.facebook.com/ads/library/?active_status=all&country=US&media_type=all&search_type=keyword_unordered&q=shoes",
  "pageInfo": {
    "adLibrarySystemStatus": {
      "systemStatus": {
        "status": "NO_KNOWN_ISSUES",
        "activeIssues": [
          { "product": "Ad Library", "status": "NO_KNOWN_ISSUES" },
          { "product": "Ad Library Report", "status": "NO_KNOWN_ISSUES" },
          { "product": "Ad Library API", "status": "NO_KNOWN_ISSUES" },
          { "product": "Branded Content", "status": "NO_KNOWN_ISSUES" }
        ]
      }
    },
    "xfbAdLibraryIsCaptchaRequired": false,
    "adLibraryPageInfo": { "pageInfo": { "relatedPages": [], "hasBlankAds": false, "hiddenAds": 0, "pageIsDeleted": false } },
    "page": { "name": "Acme Co.", "id": "863706960159979" },
    "adLibraryUser": null
  },
  "pageID": "863706960159979",
  "adArchiveID": "1573731810659177",
  "startDateFormatted": "2025-11-05T00:00:00.000Z",
  "endDateFormatted": "2025-11-06T00:00:00.000Z",
  "adArchiveId": "1573731810659177",
  "collationCount": 1,
  "collationId": "abcdef123",
  "pageId": "863706960159979",
  "snapshot": {
    "brandedContent": null,
    "pageId": "863706960159979",
    "pageIsDeleted": false,
    "pageProfileUri": "https://facebook.com/863706960159979",
    "rootResharedPost": null,
    "byline": null,
    "disclaimerLabel": null,
    "pageName": "Acme Co.",
    "pageProfilePictureUrl": "https://scontent.example/fbcdn.net/profile.jpg",
    "event": null,
    "caption": "New season essentials.",
    "ctaText": "Shop Now",
    "cards": [],
    "body": { "text": "Discover the latest styles." },
    "ctaType": "SHOP_NOW",
    "displayFormat": "IMAGE",
    "linkDescription": null,
    "linkUrl": "https://example.com/products",
    "images": [{ "url": "https://scontent.example/fbcdn.net/image.jpg" }],
    "pageCategories": ["Retail"],
    "pageLikeCount": 12345,
    "title": "Acme Co.",
    "videos": [],
    "isReshared": false,
    "extraLinks": [],
    "extraTexts": [],
    "extraImages": [],
    "extraVideos": [],
    "countryIsoCode": "US",
    "brazilTaxId": null,
    "additionalInfo": null,
    "ecCertificates": [],
    "currentPageName": "Acme Co.",
    "pageEntityType": "PAGE",
    "pageIsProfilePage": false
  },
  "isActive": true,
  "hasUserReported": false,
  "reportCount": null,
  "menuItems": [],
  "stateMediaRunLabel": null,
  "pageIsDeleted": false,
  "pageName": "Acme Co.",
  "impressionsWithIndex": { "impressionsText": "1K–2K", "impressionsIndex": -1 },
  "gatedType": null,
  "categories": [],
  "isAaaEligible": false,
  "containsDigitalCreatedMedia": false,
  "reachEstimate": null,
  "currency": "USD",
  "spend": 150,
  "endDate": 1762416000,
  "publisherPlatform": ["FACEBOOK", "INSTAGRAM"],
  "startDate": 1762329600,
  "containsSensitiveContent": false,
  "totalActiveTime": null,
  "regionalRegulationData": {
    "finserv": { "isDeemedFinserv": false, "isLimitedDelivery": false },
    "twAntiScam": { "isLimitedDelivery": false }
  },
  "hideDataStatus": null,
  "fevInfo": null,
  "adId": "1234567890",
  "targetedOrReachedCountries": ["US", "CA"],
  "aboutPage": {
    "url": "https://www.facebook.com/AcmeCo",
    "title": "Acme Co.",
    "description": "Official page for Acme Co."
  }
}

Count-only summary row (when onlyTotal is true)

{
  "sourceUrl": "https://www.facebook.com/ads/library/?active_status=active&country=US&media_type=all&search_type=keyword_unordered&q=shoes",
  "label": "Source 1",
  "totalAdsCount": 123,
  "aboutPage": {
    "url": "https://www.facebook.com/AcmeCo",
    "title": "Acme Co.",
    "description": "Official page for Acme Co."
  }
}

Notes:

• aboutPage appears when includeAboutPage is enabled (for Page sources).
• Some fields may be null or empty arrays when Meta’s Ad Library does not expose them for a given ad.

FAQ

Do I need to provide Ad Library links, or can I use page URLs?

You can use either. Add Facebook Page URLs or Ad Library links in startUrls. The actor detects the type automatically and applies defaults like countryCode and activeStatus for page sources.

Can I get a quick total without saving every ad?

Yes. Set onlyTotal to true to output one summary row per source with totalAdsCount. This is useful for quick audits and monitoring.

How do I include the advertiser’s “About” info?

Enable includeAboutPage. For Facebook Page sources, the actor will attach lightweight public title/description text (when available) to each ad row or summary row.

What does “Enrich each ad with extra fields” do?

When isDetailsPerAd is true, the actor performs an additional lookup per ad to enrich rows with more metadata. This yields more complete records but may slow down runs.

Which regions and time windows are supported?

Use countryCode for default regions on page sources, and period to set a default time window (absolute dates like 2026-01-15 or relative like “7 days”). Ad Library links usually carry their own country and filters.

Do I need a proxy to scrape Facebook Ads Library?

Not necessarily. The actor can run without a proxy, but you can enable proxyConfiguration to use residential-only proxy routing from Apify when natural-looking traffic is preferred.

What platforms are covered — Facebook and Instagram?

Yes. The Meta Ad Library covers Facebook and Instagram. The output includes publisherPlatform so you can see where each ad ran.

How many ads can I scrape per run?

Set resultsLimit to cap totals across all sources (default 10; up to 50,000). You can also control per-source limits by using limit inside individual startUrls entries (when provided as objects).

Closing CTA / Final thoughts

Facebook Ads Library Scraper is built to turn Meta Ad Library pages and links into clean, structured ad intelligence at scale. With flexible inputs, count-only summaries, optional per-ad enrichment, and residential proxy support, it helps marketers, developers, analysts, and researchers automate competitor tracking, creative analysis, and compliance workflows. Use the Apify dataset exports or API to integrate results into your reports and pipelines — and start extracting smarter, faster ad insights today.