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

{
    "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"
    ],
    "maxItems": 100,
    "minDelay": 5,
    "maxDelay": 10,
    "maxConcurrency": 10,
    "minConcurrency": 1,
    "maxRequestRetries": 100,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"]
    }
}

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

{
    "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

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