Facebook Ads Library Scraper

Facebook Ads Library Scraper creates a structured dataset of ads collected from the Facebook Ads Library. Each dataset item represents one ad (or one advertiser in unique-advertiser mode) and can include page name, copy, creative format, platforms, dates, impressions text, destination URL, and optional advertiser-detail fields. Query the source with Ads Library URLs (startUrls), keywords (searchQueries), or advertiser page IDs (pageIds). Control the result limit with maxItems, and retrieve records through the Apify Dataset API or export them as JSON, CSV, Excel, XML, or another supported format.

Dataset at a glance

Property	Value
Source	facebook.com/ads/library
Record unit	One ad, or one advertiser when unique-advertiser mode is on
Input methods	Ads Library URLs (startUrls), keywords (searchQueries), and/or page IDs (pageIds)
Main identifiers	ad_archive_id, Ads Library URL (ads_library_url)
Delivery	Apify Dataset and API
Export formats	JSON, CSV, Excel, XML, HTML (Apify dataset exports)
Update model	Fresh records per Actor run
Pricing	$1.70 / 1,000 ads; +$1.50 / 1,000 ad details; unique-advertiser mode $1.70 / 1,000 ads scraped; Actor start $0.00005

Coverage and available records

The Actor collects public Ads Library records. Provide at least one URL, search query, or page ID.

• URL-based: startUrls accepts Ads Library search URLs. Filters encoded in the URL are used as-is.
• Keyword-based: searchQueries (for example Nike) with searchType keyword_unordered (default), keyword_exact, or page.
• Advertiser-based: pageIds scopes results to those Facebook page IDs.

Filters (used when you are not relying only on a pasted URL): country (default US, or ALL), category (all, political, housing, employment, financial), activeStatus (all, active, inactive), mediaType (all, image, meme, video), publisherPlatforms (facebook, instagram, messenger, audience_network, threads), sortBy (most_recent, impressions), startDate / endDate, impressionWindow (any, last_7_days, last_30_days, last_90_days), and isTargetedCountry.

Record types and limits:

• Ad records are collected in the default mode: page, copy, format, platforms, dates, and Ads Library permalink.
• Ad details are conditional: advertiser profile, Instagram, spend, transparency, and creative variants are returned when includeAdDetails is enabled (default false) and charged as ad-details.
• Unique-advertiser mode: uniqueAdvertisersOnly writes one row per company. Charging uses filter-run once per ad scraped, including ads collapsed as repeats (for example 100 ads from 70 companies writes 70 rows and charges 100 unique-ad events).
• Result cap: maxItems limits ads or unique advertisers (0 means unlimited; console prefill 50).

Known exclusions: content not shown in the public Ads Library is not collected; each run captures Library state at run time (no historical snapshots).

Data dictionary

Field names below match dataset record JSON properties exactly. Additional media and detail fields may appear when the Library returns them.

Field	Type	Nullable	Description	Example
record_type	string	Yes	Record kind	ad
ad_archive_id	string	No	Ads Library archive identifier; recommended deduplication key	2071991237016362
page_name	string	Yes	Advertiser page name	Acervo Inmobiliario
page_id	string	Yes	Advertiser page ID	639331409798946
body_text	string	Yes	Primary ad copy	Acervo llega a New York...
title	string	Yes	Ad title	Invierte en RD desde New York
cta_text	string	Yes	Call-to-action text	Sign up
display_format	string	Yes	Creative format	IMAGE
is_active	boolean	Yes	Whether the ad is marked active	true
start_date	string	Yes	Start date as returned	2026-08-31
publisher_platforms	string[]	Yes	Platforms where the ad ran	["FACEBOOK", "INSTAGRAM"]
impressions	string	Yes	Impressions text as shown	<100
link_url	string	Yes	Destination URL when listed	https://facebook.com/marketplace/item/...
ads_library_url	string	Yes	Ads Library permalink	https://www.facebook.com/ads/library/?id=2071991237016362
page_like_count	number	Yes	Page like count when shown	38

Detail-mode runs can add advertiser about, Instagram, spend, transparency, and creative-variant fields when includeAdDetails is enabled.

Example dataset record

Ad from a keyword search. Detail fields are absent because includeAdDetails was off.

{
  "record_type": "ad",
  "ad_archive_id": "2895769867482327",
  "page_name": "Alli Hanson",
  "page_id": "101900028661031",
  "body_text": "Nike Ja 3 Kool-Aid men’s size 9 - $85.00",
  "title": "Nike Ja 3 Kool-Aid men’s size 9",
  "cta_text": "Contact us",
  "display_format": "IMAGE",
  "is_active": true,
  "start_date": "2026-08-31",
  "publisher_platforms": ["FACEBOOK", "INSTAGRAM"],
  "impressions": "<100",
  "link_url": "https://facebook.com/marketplace/item/1046035275085979/",
  "ads_library_url": "https://www.facebook.com/ads/library/?id=2895769867482327"
}

The record above was produced with this input:

{
  "searchQueries": ["Nike"],
  "country": "US",
  "maxItems": 50,
  "includeAdDetails": false
}

Query and input reference

Input	Type	Required	Default	Accepted values	Description
startUrls	array (requestListSources)	No*	—	Facebook Ads Library URLs	URL filters are used as-is
searchQueries	array (string)	No*	— (prefill Nike)	Keywords	Each query is a separate search
searchType	string	No	keyword_unordered	keyword_unordered, keyword_exact, page	Keyword match mode
pageIds	array (string)	No*	—	Facebook page IDs	Advertiser scope
country	string	No	US	Ads Library country codes or ALL	Country dropdown
category	string	No	all	all, political, housing, employment, financial	Library category
activeStatus	string	No	all	all, active, inactive	Ad status
mediaType	string	No	all	all, image, meme, video	Media filter
publisherPlatforms	array (string)	No	—	facebook, instagram, messenger, audience_network, threads	Empty = all platforms
sortBy	string	No	most_recent	most_recent, impressions	Sort order
startDate	string	No	—	Date	Impressions from
endDate	string	No	—	Date	Impressions until
impressionWindow	string	No	any	any, last_7_days, last_30_days, last_90_days	Audience window
isTargetedCountry	boolean	No	false	true / false	Targeted-country flag
includeAdDetails	boolean	No	false	true / false	Attach detail fields (charged as ad details)
detailsConcurrency	integer	No	8	1–20	Parallel detail requests
uniqueAdvertisersOnly	boolean	No	false	true / false	One row per company; charged per ad scraped
maxItems	integer	No	0	0 or any positive integer	Cap; 0 = unlimited (console prefill 50)
proxyConfiguration	object	No	Apify proxy, RESIDENTIAL	Apify proxy groups or custom proxies	Residential proxies are recommended

* Provide startUrls, searchQueries, and/or pageIds.

Minimal request:

{ "searchQueries": ["Nike"], "country": "US" }

Advanced request (URL + details):

{
  "startUrls": [{ "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=Nike&search_type=keyword_unordered" }],
  "includeAdDetails": true,
  "maxItems": 50
}

Retrieve the data through the API

Records are delivered through the Apify Actor and Dataset APIs — not an official Meta API.

1. Start the Actor with a JSON input (console or API).
2. Wait for the run to finish, or use a synchronous endpoint if you want the response inline.
3. Retrieve items from the run's default dataset.
4. Paginate or export the dataset.

Python example:

from apify_client import ApifyClient

client = ApifyClient("YOUR-APIFY-TOKEN")

run_input = {
    "searchQueries": ["Nike"],
    "country": "US",
    "maxItems": 20,
}

run = client.actor("datascrapers/facebook-ads-scraper").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item.get("ad_archive_id"), item.get("page_name"), item.get("title"))

Apify generates ready-to-run Python, JavaScript, and cURL examples on the Actor's API tab. Do not put a real API token in shared code or URLs.

Data quality and record handling

• Conditional fields: detail fields exist only when includeAdDetails is enabled.
• Unique-advertiser charging: filter-run is charged per ad scraped, not per company row written.
• Source changes: Ads Library fields can change; unreadable values are omitted rather than fabricated.
• Deduplication: within a run, ads are identified by ad_archive_id. Across runs, records are appended.
• Normalization: dates and impressions text are stored as the Library shows them.

Export and pipeline examples

Destination	Recommended method	Typical use
PostgreSQL / Supabase	Dataset API poll or webhook consumer	Store creative archives
Google Sheets	Apify Google Sheets integration	Share competitor shortlists
BI / reporting	Dataset API JSON export	Creative and platform mix
S3 / cloud storage	Scheduled export via Apify scheduler + integration	Archival of Library snapshots

Pricing and cost examples

The Actor uses pay-per-event pricing. Each run also charges a one-time Actor start. Residential proxies are recommended. Proxy and compute are billed by your Apify plan. Event charges may be tiered on Apify paid plans.

Event	Trigger	Rate
Actor start	Once per run	$0.00005
dataset-item (Ad)	Each ad in a normal run	$0.0017 / ad ($1.70 / 1,000)
ad-details (Ad Details)	Each ad opened with details	$0.0015 / ad ($1.50 / 1,000)
filter-run (Unique Ads)	Each ad scraped in unique-advertiser mode	$0.0017 / ad scraped ($1.70 / 1,000)

Example costs (Actor start negligible; plan-tier discounts not applied):

Records	Configuration	Estimated base cost
1,000	Ads only	$1.70
1,000	Ads + details	$3.20

Estimates depend on the verified pricing model and the options selected for the run.

Limitations and responsible data use

• The Actor collects publicly accessible Facebook Ads Library records only.
• Field availability depends on what the Library renders at run time; spend and reach can be missing.
• The Actor does not provide historical snapshots unless you store them yourself.
• Large runs should use residential proxies; without them, coverage may degrade.
• You are responsible for compliance with Meta's terms of service, applicable privacy law, and any contractual obligations before using the data.

Dataset questions

What does one dataset item represent?

One ad in the default mode. In unique-advertiser mode, one company, after collapsing repeat ads.

Which field should I use as a unique identifier?

ad_archive_id for ads. page_id for advertiser-level rows. ads_library_url is a reasonable secondary key.

Are fields nullable or conditional?

Yes. Detail fields exist only when includeAdDetails is enabled. Impressions, destination URL, and like count can be missing.

Can I retrieve the records as CSV or JSON?

Yes. The dataset can be exported as JSON, CSV, Excel, XML, or HTML from the Apify Console, and queried through the Dataset API.

Does the Actor return historical data?

No. Each run captures Library state at run time. To track new creatives, schedule repeated runs and store the outputs yourself.

What counts as a billable result?

Actor start once per run ($0.00005). A normal run charges dataset-item per ad ($0.0017). Details add ad-details ($0.0015). Unique-advertiser mode charges filter-run per ad scraped ($0.0017), including collapsed repeats.

Related datasets from Data Scrapers

• Facebook Marketplace Scraper — Marketplace listings that often appear as Ads Library destinations.
• Instagram Post Scraper — Organic Instagram posts for the same advertiser pages.
• Instagram Comment Scraper — Comments on creatives that overlap Ads Library campaigns.
• TikTok Profile Scraper — Cross-platform advertiser presence.
• Yelp Scraper — Local-business records that can be joined to advertiser page names.

Data Scrapers support

Need an additional field, record type, or export workflow? Contact Data Scrapers at stardustspotlight@gmail.com. Include a sample source URL, required fields, expected record volume, and preferred delivery format.