Facebook Ads Library Scraper

What is Facebook Ads Library Scraper?

Facebook Ads Library Scraper is an Apify Actor for public Meta/Facebook Ad Library data. It accepts keyword search terms, company page IDs, company names, ad IDs, or direct Ad Library URLs and returns one dataset record per ad. Each record can include advertiser identity, creative copy, CTA text, landing page URL, media URLs, status, platform coverage, dates, and provider provenance so you can review a single ad as a structured research record.

The Actor uses provider-backed public Ad Library APIs, so it fits workflows that start with public ad discovery and end with dataset-based analysis in Apify. It is usable through Apify MCP and the Apify API. No Facebook login is required when the configured provider keys are available in the Actor environment.

Best fit and connected workflows

Use this Actor when you want structured public ad intelligence from Meta's Ad Library and you already know one of the following starting points:

• a keyword or phrase for broad discovery
• a company page ID for advertiser-specific monitoring
• a company name that can be resolved to a page ID
• a specific ad ID or public Ad Library URL for direct lookup

It connects naturally to downstream workflow steps such as:

• reviewing ad creative variations by advertiser, headline, and CTA
• grouping ads by platform, status, country, or date range
• exporting ad records for manual competitive research
• passing returned public ad references into Facebook Post Comments Scraper or Facebook Likes Scraper - Public Reactions & Profiles when your workflow continues with public engagement data for a returned Facebook record

Practical scenario

Maya works on paid social research for a direct-to-consumer brand. She starts with the company name "lululemon" and wants to review active ads in the US. She runs the Actor in companyAds mode with companyNames, country, and a moderate maxResults cap.

The returned dataset records give her:

• pageName and pageId to confirm the advertiser
• headline, adCopy, and ctaText to review the creative angle
• landingPageUrl to inspect the offer destination
• publisherPlatforms to see where the ad ran
• isActive, startDate, and endDate to understand the run window

She uses those fields to decide which creative theme to compare against her own campaign, then opens the landing page and saves the ad URL for follow-up analysis.

Input

Field	Type	Purpose
mode	string	Selects the discovery path: auto, search, companyAds, or adDetails.
searchTerms	array	Keywords or exact phrases for Ad Library search.
companyPageIds	array	Facebook Ad Library page IDs for advertiser-specific scraping.
companyNames	array	Company names to resolve to page IDs before scraping.
adIds	array	Meta Ad Library archive IDs for direct detail lookup.
adUrls	array	Public Facebook Ad Library URLs for direct lookup.
country	string	Two-letter country code such as US or ALL.
status	string	ACTIVE, INACTIVE, or ALL.
mediaType	string	Creative media filter such as IMAGE, VIDEO, or ALL.
adType	string	all or political_and_issue_ads.
searchType	string	keyword_unordered or keyword_exact_phrase.
sortBy	string	Keyword result sorting by impressions or relevance.
language	string	Optional two-letter language code.
startDate	string	Optional impression start date in YYYY-MM-DD format.
endDate	string	Optional impression end date in YYYY-MM-DD format.
maxResults	integer	Maximum number of ad records to save.
maxPagesPerSearch	integer	Maximum provider result pages per target.
enrichDetails	boolean	Fetches ad details after discovery to enrich creative fields.
includeRawData	boolean	Adds the raw provider payload to each dataset item.
provider	string	Provider selection: the routing options listed in the input schema.
requestTimeoutSecs	integer	Per-provider request timeout in seconds.

Focused input example

{
  "mode": "search",
  "searchTerms": ["running shoes", "fitness app"],
  "country": "US",
  "status": "ACTIVE",
  "mediaType": "ALL",
  "searchType": "keyword_unordered",
  "sortBy": "total_impressions",
  "maxResults": 25,
  "maxPagesPerSearch": 3,
  "enrichDetails": false,
  "provider": "auto"
}

Output

Each dataset item is one ad record. The dataset is the main output, and the Actor also writes a machine-readable run summary to the default key-value store.

Field	Type	Purpose
adId	string	Meta Ad Library archive ID.
adUrl	string	Direct Facebook Ad Library URL.
pageId	string or null	Facebook page ID running the ad.
pageName	string or null	Advertiser or page display name.
pageUrl	string or null	Facebook page or profile URL for the advertiser.
pageProfilePictureUrl	string or null	Advertiser profile image URL.
isActive	boolean or null	Current active status when exposed.
startDate	string or null	ISO timestamp for the ad start.
endDate	string or null	ISO timestamp for the ad end or scheduled end.
publisherPlatforms	array	Meta platforms such as Facebook or Instagram.
country	string or null	Country ISO code from the creative snapshot.
targetedCountries	array	Countries targeted or reached when exposed.
headline	string or null	Primary headline or first carousel card title.
adCopy	string or null	Main body text from the ad snapshot.
bodyText	string or null	Normalized body text for filtering and export.
ctaText	string or null	Call-to-action text such as Shop Now.
ctaType	string or null	Provider CTA type code.
caption	string or null	Creative caption or domain label.
linkDescription	string or null	Description attached to the landing link or card.
landingPageUrl	string or null	Destination URL when exposed.
creativeImageUrls	array	Creative image URLs.
creativeVideoUrls	array	Creative video URLs.
cards	array	Normalized carousel or card variants.
displayFormat	string or null	Meta display format code.
currency	string or null	Spend currency when exposed.
spend	object or null	Spend range object when exposed.
impressionsText	string or null	Impression range text when exposed.
reachEstimate	object or null	Reach estimate object when exposed.
categories	array	Ad categories from the provider response.
containsDigitalCreatedMedia	boolean or null	Whether Meta flags digitally created media.
containsSensitiveContent	boolean or null	Whether Meta flags sensitive content.
sourceMode	string	Input mode that produced the record.
searchTerm	string or null	Keyword or company name that produced the record.
companyPageId	string or null	Company/page ID used for company scrapes.
provider	string	Provider that returned the record.
detailEnriched	boolean	Whether the ad details endpoint enriched the record.
scrapedAt	string	ISO timestamp for extraction.

Illustrative output record

{
  "adId": "3557423444566854",
  "adUrl": "https://www.facebook.com/ads/library?id=3557423444566854",
  "pageId": "33693527731",
  "pageName": "Example Brand",
  "pageUrl": "https://www.facebook.com/examplebrand",
  "isActive": true,
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": null,
  "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
  "headline": "New season essentials",
  "adCopy": "Discover a fresh collection built for everyday training.",
  "ctaText": "Shop Now",
  "landingPageUrl": "https://example.com/collection",
  "creativeImageUrls": ["https://example.com/image.jpg"],
  "sourceMode": "companyAds",
  "searchTerm": "example brand",
  "companyPageId": "33693527731",
  "detailEnriched": false,
  "scrapedAt": "2026-01-01T12:34:56Z"
}

How it works

1. You choose a discovery mode:

   • search for keyword-based Ad Library discovery
   • companyAds for page-based advertiser scraping
   • adDetails for direct ad lookup
   • auto to try ad IDs first, then company inputs, then keyword search

2. The Actor calls public provider APIs from the primary or fallback data provider.

3. It normalizes the returned ad data into dataset items.

4. If enrichDetails is enabled, it opens the ad details endpoint after discovery and saves the enriched result.

5. It writes the dataset and the run summary to Apify storages.

The Actor reads provider credentials from these environment variables:

Pricing

This Actor uses pay per event pricing on the Apify platform. Event usage is tied to the number of saved ad records, and optional detail enrichment adds its own event usage. Platform usage for Actor runs also applies according to the live Pricing tab in the Apify console.

A simple planning example: if your run saves one hundred ads and enriches twenty of them, your cost planning should account for one hundred saved-ad events, twenty detail-enrichment events, and the standard Apify platform usage shown in the Pricing tab.

Use with AI agents (MCP)

This Actor is available through Apify MCP as a tool for retrieving structured public Meta/Facebook Ad Library records. The exact Actor identity is khadinakbar/facebook-ads-library-scraper.

Tool description: search or look up public Facebook ads by keyword, company page ID, company name, ad ID, or public Ad Library URL, then return normalized ad records with provenance fields suitable for downstream analysis.

Find active public ads for this advertiser and summarize the creative themes.

Input: use companyNames, country, status, and maxResults. If the ad record includes landing pages and platforms, include them in the summary. Return the ad URLs and explain which fields support each observation.

Output interpretation:

• adId and adUrl identify the public Ad Library record.
• pageName, pageId, and pageUrl identify the advertiser.
• headline, adCopy, ctaText, and landingPageUrl describe the creative and destination.
• publisherPlatforms, isActive, startDate, and endDate provide run context.
• provider, sourceMode, searchTerm, companyPageId, detailEnriched, and scrapedAt support provenance and auditability.

Scope and pagination:

• Use one country per request, as supported by the provider contract.
• Use maxPagesPerSearch to control how many provider pages are checked per target.
• Use maxResults as the main cap on saved records.
• When enrichDetails is enabled, expect extra provider calls for each enriched ad.

Cost guidance:

• Each saved ad record is billed as a separate event.
• Detail enrichment adds separate event usage.
• The live Pricing tab is the source of truth for the current billing view on Apify.

Apify API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const run = await client.actor('khadinakbar/facebook-ads-library-scraper').call({
  mode: 'search',
  searchTerms: ['running shoes'],
  country: 'US',
  status: 'ACTIVE',
  maxResults: 5,
});

const dataset = client.dataset(run.defaultDatasetId);
const { items } = await dataset.listItems();

console.log('First records:', items);

Best results and outcome guidance

Start with the narrowest input that matches your research goal:

• use adIds or adUrls for a specific public ad
• use companyPageIds when you already have the advertiser page ID
• use companyNames when you need resolution from a brand name
• use searchTerms for theme, category, or competitor discovery

Helpful settings from the contract:

• country: use a single country code such as US when you want location-specific results
• status: choose ACTIVE for current ads or ALL for a wider review
• searchType: choose exact phrase matching for focused research or unordered keyword matching for broader discovery
• sortBy: use impressions-first ordering for volume-oriented review, or relevance ordering for recent keyword results
• enrichDetails: enable when you want more complete creative fields and can account for extra event usage

Continue the workflow

• Then use Facebook Post Comments Scraper to add Facebook engagement evidence to records selected with Facebook Ads Library Scraper.
• Then use Facebook Followers Scraper to add Facebook engagement evidence to records selected with Facebook Ads Library Scraper.

Design note

I found that the dataset contract requires adId, adUrl, sourceMode, provider, and scrapedAt on every record. That visible requirement is a useful cue that each item is designed to carry both the ad itself and its provenance in the same row.

FAQ

When should I use search instead of companyAds?

Use search when you are exploring a theme, offer, or product category. Use companyAds when you already know the advertiser page ID or a company name that should resolve to one.

When should I use adDetails?

Use adDetails when you already have a Meta Ad Library archive ID or a public Ad Library URL and want direct record lookup.

How do I choose between companyNames and companyPageIds?

companyPageIds is the more direct route when you already have the page ID. companyNames is useful when you begin with a brand name and want the Actor to resolve it first.

What if I want only current ads?

Set status to ACTIVE and keep country specific if your research focuses on one market.

Can I keep the output small?

Yes. Set maxResults to a tight cap, keep maxPagesPerSearch low, and leave includeRawData disabled for normal runs.

Responsible use

This Actor works with public Meta/Facebook Ad Library data only. Use the returned records in ways that fit your compliance, research, and data handling requirements. The output includes public ad URLs, creative text, platform data, and provenance fields so you can review records responsibly and preserve context when sharing or analyzing results.