Facebook Ads Library Scraper

Scrape active Facebook ads with filters like keywords, dates, media type, and country

---

Overview

This actor scrapes Facebook's Ads Library to extract detailed information about active advertising campaigns. Ideal for marketers, competitors, and researchers analyzing ad strategies. Supports filtering by:

• Keywords/phrases (e.g., "free shipping")
• Date ranges (up to 2025-02-15)
• Media types (video/image/text)
• Countries (e.g., GB for UK-targeted ads)
• Ad status (active/inactive)

---

Features

• Precision Filtering: Target ads by 10+ criteria including media type, country, and exact keywords
• Dynamic Delays: Randomized delays (5-10s) between API calls to avoid detection
• Residential Proxies: Built-in Apify residential proxy rotation
• Retry Resilience: 100 retries per failed request
• Concurrency Control: Process 1-10 pages simultaneously
• Historical Range: Scrape ads up to future dates (2025-02-15 supported)

---

How to Use

1. Configure Input: Set your filters in the input JSON (see configuration below)
2. Run via Apify: Execute the actor on Apify platform
3. Export Data: Download results as JSON, CSV, or Excel
4. Analyze: Track ad creatives, sponsors, and run dates

---

Input Configuration

1{
2    "startUrls": [
3        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&is_targeted_country=false&media_type=video&q=%22free%20shipping%22&search_type=keyword_exact_phrase&start_date[min]&start_date[max]=2025-02-15"
4    ],
5    "maxItems": 100,
6    "minDelay": 5,
7    "maxDelay": 10,
8    "maxConcurrency": 10,
9    "minConcurrency": 1,
10    "maxRequestRetries": 100,
11    "proxy": {
12        "useApifyProxy": true,
13        "apifyProxyGroups": ["RESIDENTIAL"]
14    }
15}

Input Parameters

Parameter	Type	Description	Default
startUrls	Array	Facebook Ads Library URLs with your filters pre-applied	Required
maxItems	Integer	Max ads to scrape per run	100
minDelay	Integer	Minimum delay (seconds) between API calls	5
maxDelay	Integer	Maximum delay (seconds) between API calls	10
maxConcurrency	Integer	Max parallel page processing threads	10
minConcurrency	Integer	Minimum parallel threads	1
maxRequestRetries	Integer	Retry attempts for failed requests	100
proxy	Object	Residential proxy configuration	Apify Proxy

---

Output Structure

Basic Ad Information

Field	Type	Description
FB AD Link	String	Direct URL to ad in Facebook's Transparency Library
FB Link	String	Permanent link to advertiser's Facebook profile/page
Company Name	String	Registered name of advertising entity
Website	String	Destination URL promoted in the ad

---

Ad Identification

Field	Type	Description
ad_archive_id	String	Facebook's internal archive identifier (unique per ad)
ad_id	Null	Legacy field (deprecated by Facebook)
collation_id	String	Group ID for related ads in same campaign
collation_count	Integer	Number of ads in this campaign group
page_id	String	Unique Facebook ID of advertiser's page

---

Ad Status & Timing

Field	Type	Description
is_active	Boolean	true = Currently running, false = Inactive
start_date	Integer	Unix timestamp (seconds) of ad start date
end_date	Integer	Unix timestamp (seconds) of planned end date
total_active_time	Null	Duration field (often restricted)

---

Ad Content & Format

Field	Type	Description
snapshot.body.text	String	Full text content of ad
snapshot.title	String	Headline/title of ad
snapshot.display_format	String	VIDEO, IMAGE, CAROUSEL, etc
snapshot.cta_text	String	Call-to-action button text ("Shop Now", etc)
snapshot.link_url	String	Destination URL when clicking ad
snapshot.videos	Array	Video assets (HD/SD URLs, preview images)
snapshot.images	Array	Static image URLs (empty for video ads)

---

Page/Advertiser Insights

Field	Type	Description
page_name	String	Name of Facebook page running ad
page_like_count	Integer	Total page followers/likes
page_profile_picture_url	String	Current profile image URL (expires in 24h)
page_profile_uri	String	Direct link to page profile
page_categories	Array	Facebook's classification (e.g., ["Book"])

---

Technical Metadata

Field	Type	Description
entity_type	String	PERSON_PROFILE (individual) or BUSINESS
publisher_platform	Array	Platforms where ad appears (FACEBOOK, INSTAGRAM, etc)
contains_digital_created_media	Boolean	true if contains AI-generated media
gated_type	String	Age/gender gating status (ELIGIBLE/INELIGIBLE)
is_aaa_eligible	Boolean	Auto-applied ads eligibility
hide_data_status	String	NONE = Full visibility, other values indicate partial hiding

---

Compliance & Regulations

Field	Type	Description
political_countries	Array	Countries where ad is classified as political
regional_regulation_data	Object	Financial service (finserv) and scam prevention (tw_anti_scam) flags
state_media_run_label	Null	For government-affiliated ads (restricted)

---

User Interaction Data

Field	Type	Description
report_count	Null	Number of user reports (often restricted)
has_user_reported	Boolean	true if current user flagged this ad

---

Monetization & Reach

Field	Type	Description
spend	Null	Ad budget (restricted for non-political ads)
reach_estimate	Null	Potential audience size (restricted)
currency	String	Empty unless spend data available

---

System Flags

Field	Type	Description
contains_sensitive_content	Boolean	Facebook's NSFW detection flag
hidden_safety_data	Boolean	true if restricted for policy violations
fev_info	Null	Fact-checking verification data (restricted)

---

Miscellaneous

Field	Type	Description
categories	Array	Legacy categorization (["UNKNOWN"] common)
menu_items	Array	Context menu options (empty in API response)
targeted_or_reached_countries	Array	Geo-targeting list (often empty)

---

Key Notes

1. Timestamps: Convert Unix values (e.g., 1734681600 → 2024-12-20T00:00:00Z)
2. Null Fields: Indicate restricted data per Facebook's policies
3. Media URLs: Expire quickly - download within 24 hours
4. Political Ads: Requires special permissions to access spend/reach data

Key fields will include:

• Ad creative (text/images/video URLs)
• Sponsor page details
• Impressions estimate
• Active dates
• Targeting parameters
• Call-to-action buttons
• Political disclaimer (if applicable)

---

Why This Scraper?

• Compliance: Follows Facebook's rate limits and robots.txt
• Stealth: Residential proxies + random delays mimic human behavior
• Depth: Captures 30+ data points per ad including edits history
• Future-Proof: Handles Facebook's frequent UI/API changes

---

Use Cases

• Track competitor ad strategies in real-time
• Analyze seasonal campaign patterns
• Archive political ads for transparency
• Monitor trademark violations

---

Explore More Scrapers

If you found this Apify Smartbuyglasses Scraper useful, be sure to check out our other powerful scrapers and actors at memo23's Apify profile. We offer a wide range of tools to enhance your web scraping and automation needs across various platforms and use cases.

Support

• For issues or feature requests, please use the Issues section of this actor.
• If you need customization or have questions, feel free to contact the author:
  • Author's website: https://muhamed-didovic.github.io/
  • Email: muhamed.didovic@gmail.com

Additional Services

• Request customization or whole dataset: muhamed.didovic@gmail.com
• If you need anything else scraped, or this actor customized, email: muhamed.didovic@gmail.com
• For API services of this scraper (no Apify fee, just usage fee for the API), contact: muhamed.didovic@gmail.com
• Email: muhamed.didovic@gmail.com