🔍 Facebook Ads Scraper Pro - Ad Library Intelligence

Extract comprehensive data from Facebook's Ad Library with real-time batch pushing, advanced filtering, and full ad-detail enrichment.

Search Keywords & Advertisers & URLs → Stream Real-Time Ad Data → Get Complete Analytics

🎬 Video Tutorial

https://www.youtube.com/watch?v=yNSIhZcDlNY

💎 Pricing Tiers - Choose Your Plan

The Actor automatically detects whether your Apify account is on a free or a paid plan — you don't configure anything. The plan decides two things: how many results a single run returns, and which proxy network the run uses.

	Free plan	Paid plan
Results per run	200 maximum (a sample)	♾️ Unlimited
Proxy network	Apify Proxy (shared residential pool)	Dedicated premium proxy
Ad Library data & fields	Full — nothing is stripped out	Full
All filters & search modes	✅ Included	✅ Included
Media assets (images & video)	✅ Included	✅ Included
Best for	Evaluating the output before you commit	Production, agencies, large datasets

FREE PLAN ✅ — try before you subscribe

Get started with no upfront cost. You get the complete data shape, just not the complete dataset.

Included:

✅ Full access to Facebook Ad Library data — every field, nothing redacted
✅ Multi-language & multi-country filtering
✅ Real-time batch pushing (results appear as they're collected)
✅ Complete media asset extraction (images & videos)
✅ All filtering options (date ranges, platforms, categories)

Limits:

🔒 200 results per run — a hard cap, counted across the whole run, not per query. A free run asking for 5 keywords × 100 results still stops at 200 results in total. The run then finishes normally (SUCCEEDED) — a short result set is the cap, not a failure.
⚠️ Apify Proxy (shared residential pool) only — the dedicated premium proxy is a paid-plan benefit
⚠️ Occasional connection interruptions on the shared pool

Think of a free run as a free sample. Run your real query, inspect the fields, check the ad creatives and the EU reach data, confirm it fits your pipeline — then subscribe and re-run the exact same input to get everything.

👉 Subscribe to a paid Apify plan to remove the 200-result cap.

PAID PLAN ⭐ RECOMMENDED FOR PRODUCTION

Upgrade for unlimited results and enterprise-grade reliability

All Free Plan features PLUS:

🚀 No 200-result cap - Every run returns the full result set
🚀 Dedicated premium proxy - Your own reliable connection, not the shared pool
🚀 No rate limiting - Unlimited continuous scraping
🚀 100% success rate - Stable, uninterrupted operations
🚀 Extract ∞+ ads per query - No slowdowns or blocks
🚀 Perfect for production use - Enterprise-ready infrastructure
🚀 Consistent performance - No random connection errors

Why upgrade?

Get all your data: The 200-result sample cap is lifted entirely
Avoid interruptions: Your dedicated proxy won't hit Facebook's rate limits
Reliability: No HTTP errors or temporary blocks
Scale effortlessly: Handle large datasets with perfect stability
Best for agencies: Reliable results for client reports and production systems
Zero downtime: 24/7 stable scraping without worries

🔒 The Free-Plan 200-Result Cap, in Detail

What it is: a free-plan run pushes at most 200 results in total, then stops cleanly.

How it behaves:

The cap is run-wide, not per keyword, per URL or per advertiser. Five queries at maxResultsPerQuery: 100 will not return 500 results on a free plan — they return 200.
The run still succeeds. It is not an error, a crash, or a block.
You are never charged for results you don't receive — the cap is applied before billing, so a capped run bills for exactly the results in your dataset.
Once the cap is reached the Actor stops fetching immediately — it doesn't keep making requests for ads it can't give you.
Every free run states the cap twice: once at the start of the log, and once in the finish summary and the run's status message.

What you'll see in the log when a free run hits the cap:

════════════════════════════════════════════════════════════════════════════════
🔒 FREE PLAN SAMPLE — 200 of a possible unlimited results returned
════════════════════════════════════════════════════════════════════════════════
   This run stopped at the free-plan limit of 200 results.
   What you are looking at is a SAMPLE — the full result set is larger.

   👉 Subscribe to any paid Apify plan to unlock ALL results:
      https://console.apify.com/billing/subscription
════════════════════════════════════════════════════════════════════════════════

And on the finished run header:

✅ Sample complete: 200 results (free-plan limit of 200 per run reached).
   Subscribe to a paid Apify plan to unlock all results.

To remove the cap: subscribe to any paid Apify plan and re-run the same input. Nothing in your Actor input changes — the Actor detects the upgrade automatically on the next run.

🚀 Quick Start

Option 1: Run as Batch Job (One-Time Execution)

Perfect for: One-off scraping tasks, scheduled runs, offline processing

apify call dz-omar/facebook-ads-scraper-pro --input input.json

Input format (input.json):

{
  "searchQueries": ["nike", "adidas"],
  "searchAdvertisers": ["15087023444"],
  "maxResultsPerQuery": 50,
  "countries": ["US"],
  "activeStatus": "ACTIVE",
  "mediaType": "IMAGE"
}

Process Flow:

Actor starts
Processes your request
Returns results
Actor stops

Option 2: Run with Ad Library URLs (New in v0.2) 🔗

Perfect for: Copying searches directly from Facebook's Ad Library website, or fetching a specific ad by ID

{
  "URLAds": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&media_type=video"
    },
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=adidas"
    }
  ],
  "maxResultsPerQuery": 50
}

How URL Mode works:

Go to Facebook Ad Library and set up your search
Copy the URL from your browser
Paste it into the URLAds field
All filters from the URL (country, language, date range, media type, platforms, sort order) are extracted automatically
The actor parses each URL and runs the search for you

📌 Single ad links supported: URLs with ?id= fetch that specific ad directly no search query needed:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?id=907653308384731" }
  ],
  "enrichWithAdDetails": true
}

Combining URL Mode with Manual Search:

You can provide URLs alongside keyword and advertiser searches all run sequentially:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=pokemon&media_type=video" }
  ],
  "searchQueries": ["apify"],
  "searchAdvertisers": ["Nike", "15087023444"],
  "maxResultsPerQuery": 50,
  "activeStatus": "ALL",
  "adType": "ALL"
}

Execution order:

🔗 All URLAds are processed first (each URL uses its own filters from the URL)
🏢 Then searchAdvertisers are resolved and scraped (using the input schema filters)
🔍 Then searchQueries are run as keyword searches (using the input schema filters)

maxResultsPerQuery controls the maximum ads collected per URL, per advertiser page, and per keyword query.

🔒 On a free Apify plan, every run stops at 200 results in total — across all URLs, advertisers and queries combined — no matter what maxResultsPerQuery is set to. That's your free sample. Subscribe to a paid plan to unlock the full result set with the same input.

📋 Input Parameters

Parameter	Type	Default	Description
`URLAds`	array	`[]`	Facebook Ad Library URLs to scrape directly (new in v0.2)
`searchQueries`	array	`[]`	Keywords to search (e.g., `["nike", "adidas"]`)
`searchAdvertisers`	array	`[]`	Advertiser names or page IDs
`maxResultsPerQuery`	integer	`10`	Max ads per URL / per query / per advertiser page. Free plan: the run still stops at 200 results in total regardless of this value
`batchSize`	integer	`30`	Ads per batch request
`countries`	array/string	`["ALL"]`	Country codes (e.g., `["US", "GB", "FR"]`)
`contentLanguages`	array	`[]`	Language codes (e.g., `["en", "es", "fr"]`)
`activeStatus`	string	`"ALL"`	`"ALL"`, `"ACTIVE"`, `"INACTIVE"`
`adType`	string	`"ALL"`	Ad category filter
`mediaType`	string	`"ALL"`	Media type filter
`publisherPlatforms`	array	`[]`	Platforms to search
`sortBy`	string	`"SORT_BY_TOTAL_IMPRESSIONS"`	Sort method
`startDate`	string	`null`	Start date (YYYY-MM-DD)
`endDate`	string	`null`	End date (YYYY-MM-DD)
`enrichWithAdDetails`	boolean	`false`	Fetch full ad details per result (advertiser info, targeting, payer/beneficiary, violations)

⚠️ Important: Input Requirements

At least one of these MUST be provided:

URLAds - Contains Facebook Ad Library URLs
searchQueries - Contains search keywords
searchAdvertisers - Contains advertiser names/page IDs

You can provide any combination all are processed sequentially.

Invalid Input Examples (Will Fail):

{
  "maxResultsPerQuery": 50
}

❌ Error: "No input provided. Supply either URLAds, searchQueries, or searchAdvertisers"

{
  "searchQueries": [],
  "searchAdvertisers": []
}

❌ Error: "Both arrays are empty - no search criteria provided"

Valid Input Examples:

{
  "URLAds": [{ "url": "https://www.facebook.com/ads/library/?q=nike&country=US" }]
}

✅ Valid - Parses the URL and runs the search

{
  "searchQueries": ["nike"]
}

✅ Valid - Uses all defaults, searches for "nike"

{
  "searchAdvertisers": ["15087023444"]
}

✅ Valid - Searches all ads from page ID

{
  "URLAds": [{ "url": "https://www.facebook.com/ads/library/?q=pokemon&media_type=video" }],
  "searchQueries": ["marketing"],
  "searchAdvertisers": ["Nike", "Apple"],
  "maxResultsPerQuery": 100,
  "countries": ["US"]
}

✅ Valid - Runs URL first, then advertisers, then keywords

🔍 Enriching Results with Ad Details

By default, each result contains the core ad data. Enable enrichWithAdDetails to fetch a richer detail page per ad:

{
  "searchQueries": ["nike"],
  "maxResultsPerQuery": 50,
  "enrichWithAdDetails": true
}

Extra data included when enabled:

Advertiser info: page about text, category, likes, profile photo, cover photo, verification status
Instagram: username, followers, verification status
Targeting (EU): location audience, age/gender breakdown, total EU reach
Payer/Beneficiary: who paid for and benefits from the ad
Violations: any policy violation types flagged by Facebook

⚠️ Performance note: Each ad requires one extra API request. Scraping will be slower.

Valid Values Reference

Ad Types:

ALL - All ad types
POLITICAL_AND_ISSUE_ADS - Political/election ads
HOUSING_ADS - Real estate & housing
EMPLOYMENT_ADS - Job postings
CREDIT_ADS - Financial products

Media Types:

ALL - All media types
IMAGE - Static images only
VIDEO - Video ads only
MEME - Text-heavy images
IMAGE_AND_MEME - Both image types
NONE - Text-only ads

Publisher Platforms:

FACEBOOK - Main Facebook feed
INSTAGRAM - Instagram feed & stories
MESSENGER - Facebook Messenger
WHATSAPP - WhatsApp Business
THREADS - Threads social platform
AUDIENCE_NETWORK - Third-party apps/sites

Sort Methods:

SORT_BY_TOTAL_IMPRESSIONS - Most viewed first (default)
SORT_BY_RELEVANCY_MONTHLY_GROUPED - Most recent first

📊 Ad Data Structure

Each ad object contains:

{
  "id": "606497791453836",
  "page_id": "15087023444",
  "page_name": "Nike",
  "page_url": "https://facebook.com/Nike",
  "page_profile_picture_url": "https://...",
  "page_likes": 5000000,
  "page_category": "Brand",
  
  "text": "Just Do It campaign",
  "title": "Ad Title",
  "caption": "Visit our store",
  "link_url": "https://nike.com",
  "cta_text": "Learn More",
  
  "media": {
    "type": "image|video",
    "primary_thumbnail": "https://...",
    "images": ["..."],
    "videos": ["..."]
  },
  
  "additional_assets": {
    "images": ["..."],
    "links": ["..."],
    "texts": ["..."],
    "videos": ["..."]
  },
  
  "start_date": "2024-01-15",
  "end_date": "2024-02-15",
  "is_active": true,
  
  "platforms": ["FACEBOOK", "INSTAGRAM"],
  "countries": ["US", "GB", "CA"],
  "ad_category": "MARKETING",
  
  "contains_sensitive_content": false,
  "scraped_at": "2026-01-25T23:14:50Z",

  // Only present when enrichWithAdDetails: true
  "ad_details": {
    "advertiser": {
      "page": { "id": "15087023444", "about": { "text": "https://nike.com" } },
      "ad_library_page_info": {
        "page_info": {
          "ig_username": "nike",
          "ig_followers": 306000000,
          "ig_verification": true,
          "page_verification": "BLUE_VERIFIED",
          "page_cover_photo": "https://...",
          "entity_type": "BRAND"
        },
        "page_spend": { "is_political_page": false }
      }
    },
    "aaa_info": {
      "targets_eu": true,
      "gender_audience": "All",
      "age_audience": { "min": 18, "max": 65 },
      "eu_total_reach": 500000,
      "location_audience": [{ "name": "France", "type": "countries" }, "..."],
      "age_country_gender_reach_breakdown": ["..."],
      "payer_beneficiary_data": [{ "payer": "Nike Inc.", "beneficiary": "Nike" }],
      "has_violating_payer_beneficiary": false,
      "is_ad_taken_down": false
    },
    "violation_types": [],
    "verified_voice_context": {
      "types": ["UNCATEGORIZED"],
      "ad_library_all_geo_fin_serv_info": { "finserv_data": [] }
    }
  }
}

🎯 Search Modes Explained

1. URL Mode (New in v0.2) 🔗

Paste Ad Library URLs directly all filters are extracted automatically:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&media_type=video" }
  ],
  "maxResultsPerQuery": 100
}

Use Case: You've already set up the perfect search on Facebook's Ad Library website just copy the URL and let the actor handle it.

📌 Single ad links also supported:

URLs containing ?id= fetch that one specific ad directly no search, no pagination:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?id=907653308384731" }
  ]
}

Pair it with enrichWithAdDetails: true to get the full advertiser, targeting, and payer/beneficiary data for that ad:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?id=907653308384731" }
  ],
  "enrichWithAdDetails": true
}

2. Keyword Search

Search for ads by keywords or brand names:

{
  "searchQueries": ["nike", "adidas"],
  "maxResultsPerQuery": 100
}

Use Case: Find all ads mentioning your keywords across all advertisers

⚠️ Important Keyword Search is Broad by Design

When using searchQueries, Facebook Ads Scraper Pro performs a keyword search across all advertisers. This means it matches any ad whose text, title, or page name contains your keyword not just the brand you may have in mind.

For example:
{
  "searchQueries": ["SHEIN"]
}
This will return ads from SHEIN Brasil, SHEIN KIDS, SHEIN Mexico, and any other page or ad copy containing the word "SHEIN". The impression-based ranking may also surface different ads than you'd expect when targeting a specific page.

If you want precise, targeted results for a specific advertiser, use one of these instead:
🏢 searchAdvertisers resolves the brand name to its exact Facebook page(s) and fetches only their ads:
{ "searchAdvertisers": ["SHEIN"] }
🔗 URLAds copy the URL directly from Facebook's Ad Library after setting up your exact search filters:
{ "URLAds": [{ "url": "https://www.facebook.com/ads/library/?q=SHEIN&country=ALL" }] }

3. Advertiser Search

Search ads from specific Facebook pages:

{
  "searchAdvertisers": ["Nike", "15087023444"],
  "maxResultsPerQuery": 100
}

Use Case: Monitor what a specific brand/company is advertising. Names are resolved via Facebook's typeahead API all exact-match pages are scraped.

4. Combined Search

URLs, keywords, and advertisers all in one run:

{
  "URLAds": [
    { "url": "https://www.facebook.com/ads/library/?q=pokemon&country=ALL&media_type=video" }
  ],
  "searchQueries": ["marketing"],
  "searchAdvertisers": ["Nike", "Apple"],
  "maxResultsPerQuery": 50
}

Use Case: Run a comprehensive competitive analysis in a single actor run. URLs are processed first with their own filters, then advertisers and keywords run with the input schema filters.

🌍 Supported Countries & Languages

Countries (200+)

ALL, US, GB, CA, AU, DE, FR, ES, IT, BR, IN, JP, DZ, and 190+ more ISO 2-letter codes

Languages (100+)

en, es, fr, de, it, pt, ja, ko, zh, ar, and 90+ more ISO 2-letter codes

⚙️ Limits & Capacity

Aspect	Details
Requests	No hard limit, respects Facebook's rate limits
Page size	~10 ads per request — a Facebook-side cap, not a setting
Results per Query	1-10,000 ads per query
Results per Run (free plan)	200 total — a sample; subscribe to unlock all results
Results per Run (paid plan)	Unlimited — bounded only by your own `maxResultsPerQuery` and budget
Delivery	Real-time batch pushing — results appear in the dataset as they arrive
Memory Usage	No limits - handles 1000s of ads

🛡️ Error Handling & Migration

Automatic Retry Logic

Failed queries are retried up to 3 times
Exponential backoff prevents rate limiting
Failed queries are logged but don't stop the job

Migration Handling

Server automatically handles Apify platform migrations:

{"type":"migrating","message":"Server is migrating to new instance","timestamp":"..."}

Connection behavior:

Connection closes gracefully
Reconnect to resume if interrupted
No data loss - state is preserved

🛠️ Troubleshooting

URL Mode Issues

URL not recognized: Make sure you're copying from https://www.facebook.com/ads/library/...
Filters not applied: Check that the URL contains the expected query parameters
Wrong result count: Use maxResultsPerQuery to control how many ads are fetched per URL

Search Issues

No results: Try broader keywords or check spelling
Limited data: Increase maxResultsPerQuery or expand date ranges
Missing recent ads: Facebook may have indexing delays

Free Plan Issues

"I only got 200 results": That's the free-plan cap, not a bug — it applies to the whole run, not per query. Subscribe to a paid plan and re-run the same input to get everything. See The Free-Plan 200-Result Cap, in Detail above.
"The run finished early": Check the end of the log for the 🔒 FREE PLAN SAMPLE banner — if it's there, the run stopped at the cap and completed successfully.
Intermittent failures: Free runs use the shared Apify Proxy pool. Upgrading to a paid plan switches you to the dedicated premium proxy for stability.
Slow performance: Reduce batch size or split into multiple smaller runs
Rate limiting errors: Wait a few minutes before retrying, or upgrade to a paid plan

Geographic Filtering

Empty countries String: Use "ALL" for global targeting
Wrong country codes: Use ISO 2-letter codes (US, not USA)
Missing regional ads: Some ads may not be available in all regions

Media Access

Missing media URLs: Some ads may have expired media
Broken links: Media URLs may expire after extended periods
Empty arrays: Check if media type matches your filter

Performance Optimization

Large datasets: Use date ranges to limit scope
Free plan limits: Free runs stop at 200 results in total — subscribe to a paid plan for 1000+ ads per query
Better results: Upgrade to a paid plan for the dedicated proxy and enterprise-grade stability

📈 Business Intelligence Applications

🎯 Competitive Intelligence

Ad Strategy Analysis: Track competitor creative strategies
Platform Presence: Monitor competitor activity across platforms
Campaign Duration: Analyze campaign lengths and timing

🚀 Campaign Optimization

Creative Inspiration: Download high-quality assets
CTA Analysis: Study effective call-to-action strategies
Performance Benchmarking: Compare page engagement metrics

📊 Market Research

Industry Trends: Filter by category for sector analysis
Geographic Patterns: Analyze regional strategies
Content Evolution: Track messaging changes over time

🤝 Support & Resources

Get Help

🌐 Website: flowextractapi.com
📧 Email: flowextractapi@outlook.com
🙋 Apify Profile: FlowExtract API
💬 GitHub Issues: FlowExtractAPI

Social Media

💼 LinkedIn: flowextract-api
🐦 Twitter: @FlowExtractAPI
📱 Facebook: flowextractapi

🌟 Related Actors by FlowExtract API

🎬 Video & Media

YouTube Transcript Extractor - Extract transcripts with timestamps
YouTube Scraper Pro - Complete channel and playlist extraction
Zoom Scraper - Download recordings and transcripts
Loom Scraper - Loom video and transcript extraction

🏠 Real Estate

Idealista Scraper API - Spanish property data with API
Idealista Scraper - Real estate listings extractor

🛠️ Developer Tools

Screenshot - Fast webpage screenshots
Ultimate Screenshot - Advanced screenshot tool
Network Security Scanner - Security vulnerability scanner

📱 Social Media

Facebook Ads Scraper Pro - Extract Facebook ads data

⚖️ Legal & Compliance

Public Data Access: Only processes publicly available Facebook Ad Library data
Rate Limiting: Respects Facebook's service limits and terms of use
Data Protection: No storage of personal information or unauthorized data collection
Commercial Use: Suitable for business intelligence and research applications

Name		Name	Last commit message	Last commit date
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation