Facebook Ads Library Scraper

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

💡 Prefer to pay only for what you scrape? This actor bills a flat monthly rate. The newer Facebook Ads Library Scraper — pay-per-event does the exact same job billed per result from $0.3 / 1,000. Apify is retiring monthly-rental pricing, so moving now locks in the lower cost and skips the automatic migration later.

---

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

• 🔎 Keyword Search (no URL needed): Just enter search terms, countries, and status — the actor builds the Meta Ad Library query for you. No hand-crafted URLs.
• Flexible URL Input: Supports both Ads Library URLs and direct Facebook page URLs (e.g., https://www.facebook.com/SHEINOFFICIAL)
• Automatic Page ID Extraction: Automatically extracts page IDs from Facebook page URLs and converts them to Ads Library format
• 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

Easiest — Search by keyword (no URL needed)

Just type what you want and the actor builds the Meta Ad Library query for you — no need to hand-craft a URL.

{
    "searchTerms": ["nike", "weight loss"],
    "searchCountries": ["US", "GB"],
    "adActiveStatus": "active",
    "mediaType": "all",
    "searchMode": "keyword_unordered",
    "maxItems": 100,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Field	What it does
searchTerms	Keywords or brand names — each term is searched separately
searchCountries	ISO 2-letter codes (US, GB, …) or ALL; each is queried per term
adActiveStatus	active, inactive, or all
mediaType	all, image, or video
searchMode	keyword_unordered (broad — any word) or keyword_exact_phrase (auto-quoted)
startDateMin / startDateMax	Only ads that started in this date window (YYYY-MM-DD)

Need political/housing/employment ad categories, a specific publisher platform, or a content language? Paste a full Ads Library URL via startUrls instead (see the advanced examples below).

Example 1: Using Facebook Page URLs (Direct)

{
    "startUrls": [
        "https://www.facebook.com/SHEINOFFICIAL",
        "https://www.facebook.com/Nike",
        "https://www.facebook.com/usemotionapp"
    ],
    "maxItems": 100,
    "minDelay": 5,
    "maxDelay": 10,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"]
    }
}

Example 2: Using Ads Library URLs (Advanced Filtering)

{
    "startUrls": [
        "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",
        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&view_all_page_id=103598131567301"
    ],
    "maxItems": 100,
    "minDelay": 5,
    "maxDelay": 10,
    "maxConcurrency": 10,
    "minConcurrency": 1,
    "maxRequestRetries": 100,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"]
    }
}

Supported URL Formats

The scraper accepts two types of URLs:

1. Direct Facebook Page URLs

https://www.facebook.com/SHEINOFFICIAL
https://www.facebook.com/Nike
https://www.facebook.com/usemotionapp

How it works:

• The scraper automatically fetches the page with authentication
• Extracts the page ID (e.g., 100064280965738 for SHEIN)
• Converts to Ads Library URL format
• Fetches all ads for that page

2. Facebook Ads Library URLs (with filters)

https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&media_type=video&q=keyword
https://www.facebook.com/ads/library/?active_status=all&search_type=page&view_all_page_id=123456

Benefits:

• Apply advanced filters (country, media type, keywords, date ranges)
• Search by page ID directly
• Filter by active/inactive status

---

Input Parameters

Parameter	Type	Description	Default
startUrls	Array	Facebook page URLs (e.g., https://www.facebook.com/SHEINOFFICIAL) or Ads Library URLs with filters	Required
maxItems	Integer	Max ads to scrape per run	10000
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

{
    "FB AD Link": "https://www.facebook.com/ads/library/?id=554396010944539",
    "FB Link": "https://www.facebook.com/usemotionapp/",
    "Company Name": "Motion",
    "Website": "usemotion.com",
    "ad_archive_id": "554396010944539",
    "ad_id": null,
    "archive_types": [],
    "categories": [
        "UNKNOWN"
    ],
    "collation_count": 3,
    "collation_id": "693850463625155",
    "contains_digital_created_media": false,
    "contains_sensitive_content": false,
    "currency": "",
    "end_date": 1750921200,
    "entity_type": "PERSON_PROFILE",
    "fev_info": null,
    "finserv_ad_data": null,
    "gated_type": "ELIGIBLE",
    "has_user_reported": false,
    "hidden_safety_data": false,
    "hide_data_status": "NONE",
    "impressions_with_index": {
        "impressions_text": null,
        "impressions_index": -1
    },
    "is_aaa_eligible": true,
    "is_active": true,
    "is_profile_page": false,
    "menu_items": [],
    "page_id": "103598131567301",
    "page_is_deleted": false,
    "page_name": "Motion",
    "political_countries": [],
    "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM"
    ],
    "reach_estimate": null,
    "regional_regulation_data": {
        "finserv": {
            "is_deemed_finserv": false,
            "is_limited_delivery": false
        },
        "tw_anti_scam": {
            "is_limited_delivery": false
        }
    },
    "report_count": null,
    "snapshot": {
        "body": {
            "text": "Be 137% more productive."
        },
        "branded_content": null,
        "brazil_tax_id": null,
        "byline": null,
        "caption": "usemotion.com",
        "cards": [],
        "cta_text": "Saznajte više",
        "cta_type": "LEARN_MORE",
        "country_iso_code": null,
        "current_page_name": "Motion",
        "disclaimer_label": null,
        "display_format": "IMAGE",
        "event": null,
        "images": [
            {
                "original_image_url": "https://scontent.fhan3-3.fna.fbcdn.net/v/t39.35426-6/502492793_1054293803317783_201280583862847808_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=79MpJoaVUG4Q7kNvwGzgwMb&_nc_oc=AdmiCbM4h7hHcjzS78hBXhh-kqbqOiyZbu5YcnjTmYi8fJyxiRCghxaZKOkyGakvKAg&_nc_zt=14&_nc_ht=scontent.fhan3-3.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfOBxg0zBZE5I8h5tQ7QlqjO3BHFUqgBjNGOIwlhhhXnmQ&oe=6863D5BA",
                "resized_image_url": "https://scontent.fhan3-3.fna.fbcdn.net/v/t39.35426-6/502652905_549954111382058_5494539714617214349_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=11YsJKhHL9gQ7kNvwFQyF27&_nc_oc=AdmwIyTGYmabIQ3WHIslhtAT6bmK-pIkXvG6fem73EUvNaeqpRlhhRrs6w-ml-ufqI8&_nc_zt=14&_nc_ht=scontent.fhan3-3.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfN41oyHr6YPW3Oq9j2P4jT45pOn01uFJHcFHeXyg51a7A&oe=6863D380",
                "watermarked_resized_image_url": "",
                "image_crops": []
            }
        ],
        "is_reshared": false,
        "link_description": "Motion Teams | Automatically prioritize tasks, schedule meetings, and resolve calendar conflicts. Used by over 10k CEOs and professionals to improve focus, get more done, and streamline workday.",
        "link_url": "https://www.usemotion.com/teams",
        "page_categories": [
            "Software"
        ],
        "page_entity_type": "PERSON_PROFILE",
        "page_id": "103598131567301",
        "page_is_deleted": false,
        "page_is_profile_page": false,
        "page_like_count": 41998,
        "page_name": "Motion",
        "page_profile_picture_url": "https://scontent.fhan4-5.fna.fbcdn.net/v/t39.35426-6/508816737_586512144117458_1442892662474165395_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=pC-2Jifxs-kQ7kNvwHYxKPV&_nc_oc=AdlONKKEnKB8H5DdW-UAjQiF6v_oiF5LX2Nu7VArJ_JATWPzqPzqwORlya5VUYCpafM&_nc_zt=14&_nc_ht=scontent.fhan4-5.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfPizUrkt_Gl03E8xTDQCz3GBlbeCfXWC_Mkr_YRLNHjBQ&oe=6863E1F2",
        "page_profile_uri": "https://www.facebook.com/usemotionapp/",
        "root_reshared_post": null,
        "title": "AI Project Management",
        "videos": [],
        "additional_info": null,
        "ec_certificates": [],
        "extra_images": [],
        "extra_links": [],
        "extra_texts": [],
        "extra_videos": []
    },
    "spend": null,
    "start_date": 1750921200,
    "state_media_run_label": null,
    "targeted_or_reached_countries": [],
    "total_active_time": 71587,
    "data_reach": {
        "advertiser": {
            "page": {
                "about": {
                    "text": "Motion increases productivity by 137%\n\nWith automation and AI that intelligently plan your day, sched"
                },
                "is_delegate_page_with_linked_primary_profile": false,
                "id": "103598131567301"
            },
            "ad_library_page_info": null
        },
        "aaa_info": {
            "targets_eu": true,
            "location_audience": [
                {
                    "name": "Nizozemska",
                    "num_obfuscated": 0,
                    "type": "countries",
                    "excluded": false
                },
                {
                    "name": "Njemačka",
                    "num_obfuscated": 0,
                    "type": "countries",
                    "excluded": false
                }
            ],
            "gender_audience": "Svi",
            "age_audience": {
                "min": 18,
                "max": 65
            },
            "eu_total_reach": 16,
            "age_country_gender_reach_breakdown": [
                {
                    "country": "NL",
                    "age_gender_breakdowns": [
                        {
                            "age_range": "35-44",
                            "male": 1,
                            "female": 1,
                            "unknown": null
                        },
                        {
                            "age_range": "55-64",
                            "male": 1,
                            "female": null,
                            "unknown": null
                        },
                        {
                            "age_range": "18-24",
                            "male": 1,
                            "female": null,
                            "unknown": null
                        },
                        {
                            "age_range": "25-34",
                            "male": 1,
                            "female": 1,
                            "unknown": null
                        }
                    ]
                },
                {
                    "country": "DE",
                    "age_gender_breakdowns": [
                        {
                            "age_range": "55-64",
                            "male": 2,
                            "female": null,
                            "unknown": null
                        },
                        {
                            "age_range": "18-24",
                            "male": 1,
                            "female": 3,
                            "unknown": null
                        },
                        {
                            "age_range": "35-44",
                            "male": null,
                            "female": 4,
                            "unknown": null
                        }
                    ]
                }
            ],
            "payer_beneficiary_data": [
                {
                    "payer": "Motion",
                    "beneficiary": "Motion"
                }
            ],
            "has_violating_payer_beneficiary": false,
            "is_ad_taken_down": false
        },
        "violation_types": [],
        "verified_voice_context": null,
        "transparency_by_location": null
    }
}

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 (matches page_name)
Website	String	Main website domain from the ad's link (e.g., usemotion.com)

---

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)
archive_types	Array	Empty array in sample, used for ad classification
categories	Array	Facebook's classification (e.g., ["UNKNOWN"])
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	Integer	Duration in seconds the ad has been active
is_aaa_eligible	Boolean	Indicates if ad is eligible for automated ads

---

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	IMAGE for static image ads
snapshot.cta_text	String	Call-to-action button text (e.g., "Saznajte više")
snapshot.cta_type	String	Type of CTA (e.g., "LEARN_MORE")
snapshot.link_url	String	Destination URL when clicking ad
snapshot.link_description	String	Description text shown in link preview
snapshot.images	Array	Array containing image objects with URLs
snapshot.images[].original_image_url	String	Full resolution image URL
snapshot.images[].resized_image_url	String	Resized version of the image
snapshot.videos	Array	Empty array for non-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
page_profile_uri	String	Direct link to page profile
page_categories	Array	Facebook's business classification (e.g., ["Software"])
page_entity_type	String	Type of page (e.g., PERSON_PROFILE)
page_is_deleted	Boolean	Indicates if the page has been deleted
page_is_profile_page	Boolean	Indicates if this is a personal profile page

---

Technical Metadata

Field	Type	Description
entity_type	String	PERSON_PROFILE (individual) or BUSINESS
publisher_platform	Array	Platforms where ad appears (e.g., ["FACEBOOK", "INSTAGRAM"])
contains_digital_created_media	Boolean	false if contains only original media
gated_type	String	Age/gender gating status (e.g., ELIGIBLE)
hide_data_status	String	NONE = Full visibility
is_reshared	Boolean	false if this is an original post

---

Compliance & Regulations

Field	Type	Description
political_countries	Array	Empty array in sample, indicates countries where ad is political
regional_regulation_data	Object	Contains compliance flags
regional_regulation_data.finserv	Object	Financial services compliance data
regional_regulation_data.finserv.is_deemed_finserv	Boolean	If ad is considered financial service
regional_regulation_data.finserv.is_limited_delivery	Boolean	If ad has delivery restrictions
regional_regulation_data.tw_anti_scam	Object	Taiwan anti-scam regulations
state_media_run_label	Null	For government-affiliated ads

---

User Interaction Data

Field	Type	Description
report_count	Null	Number of user reports (restricted)
has_user_reported	Boolean	false if current user hasn't reported the ad
finserv_ad_data	Null	Financial service ad data (restricted)
fev_info	Null	Fact-checking verification data

---

Monetization & Reach

Field	Type	Description
spend	Null	Ad budget (restricted)
reach_estimate	Null	Potential audience size (restricted)
currency	String	Empty string when spend data is restricted
impressions_with_index	Object	Contains impression data
impressions_with_index.impressions_text	Null	Formatted impressions text
impressions_with_index.impressions_index	Integer	-1 when data is restricted

---

System Flags

Field	Type	Description
contains_sensitive_content	Boolean	false if content is not flagged as sensitive
hidden_safety_data	Boolean	false if no safety restrictions are applied
is_profile_page	Boolean	false if not a profile page ad
menu_items	Array	Empty array in sample

---

Audience & Targeting

Field	Type	Description
targeted_or_reached_countries	Array	Empty array in sample
data_reach	Object	Detailed audience reach data
data_reach.advertiser	Object	Information about the advertiser
data_reach.advertiser.page.about.text	String	Page description text
data_reach.aaa_info	Object	Detailed audience analytics
data_reach.aaa_info.targets_eu	Boolean	true if targeting EU countries
data_reach.aaa_info.location_audience	Array	Targeted locations
data_reach.aaa_info.gender_audience	String	Targeted gender (e.g., "Svi" for all)
data_reach.aaa_info.age_audience	Object	{min, max} age range
data_reach.aaa_info.eu_total_reach	Integer	Estimated reach in EU
data_reach.aaa_info.age_country_gender_reach_breakdown	Array	Detailed breakdown by country, age, and gender

---

Key Notes

1. Timestamps: Convert Unix timestamps (e.g., 1750921200 → 2025-02-24T23:00:00Z)
2. Null Fields: Indicate restricted data per Facebook's policies
3. Media URLs: May expire - download promptly
4. Audience Data: Includes detailed demographic breakdowns when available
5. Compliance: Contains regulatory information for different regions

Key fields include:

• Ad creative (text/images/video URLs)
• Sponsor page details and metrics
• Detailed audience targeting information
• Active dates and duration
• Compliance and regulation data
• Call-to-action configuration

---

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

Monitor every major ad platform with the full ads-transparency suite:

• LinkedIn Ad Library Scraper — Ads, Impressions & Targeting — B2B competitor ads with impressions and targeting data
• TikTok Ads Scraper — TikTok creative center & ads
• X (Twitter) Ads Transparency Scraper — X's ad repository
• Google Ads Transparency Scraper — Google's ads transparency center

If you found this Facebook Ads Library Scraper useful, check out the rest of my scrapers and actors at memo23's Apify profile.

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

---

🤖 For AI Agents & LLM Apps

Compact reference for AI agents calling this actor via the Apify MCP server or the Apify API (actor: memo23/facebook-ads-library-scraper-ppe).

Purpose: Scrapes Meta's Ad Library — from keyword search terms or from pasted Ad Library / Facebook Page URLs — returning full ad records (creative, copy, advertiser page, run dates, and EU reach/transparency) with the richest schema on the Store.

Minimal input:

{
  "searchTerms": ["nike"],
  "searchCountries": ["US"],
  "maxItems": 25
}

URL variant: { "startUrls": ["https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&q=nike&search_type=keyword_unordered"], "maxItems": 25 }

Output: one row per ad — FB AD Link, FB Link, Company Name, Website, ad_archive_id, page_id, page_name, is_active, start_date, end_date, total_active_time, publisher_platform, categories, collation_count, snapshot {body.text, title, cta_text, cta_type, link_url, link_description, display_format, images[].original_image_url, videos, page_like_count, page_categories}, data_reach {aaa_info: targets_eu, eu_total_reach, age_country_gender_reach_breakdown}.

Behaviors an agent should know:

• Provide either searchTerms (with searchCountries, adActiveStatus, mediaType, searchMode) or startUrls — URLs support every Ad Library filter (dates, political/housing/employment/credit category, publisher platform, language). Each search term × country is queried separately.
• Always set maxItems (default 10000). startUrls accepts at most 5 URLs.
• startDateMin / startDateMax filter by ad start date (YYYY-MM-DD); filterDuplicatePageIds: true keeps one ad per page; includeAdReach / includeTotalActiveAds add extra output fields.
• Spend, reach_estimate, currency, and impressions are null/empty for standard commercial ads — populated mainly for regulated categories (adType political/housing/employment/credit) and EU-transparency ads.
• Media URLs (images/videos) are time-limited CDN links — download promptly.
• Pay-per-event: billed per ad emitted to the dataset (from $0.3 per 1,000 ads; reach included at no extra charge). See the Pricing tab on the actor page.