🔍 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

---

💎 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:

1. Actor starts
2. Processes your request
3. Returns results
4. 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:

1. Go to Facebook Ad Library and set up your search
2. Copy the URL from your browser
3. Paste it into the URLAds field
4. All filters from the URL (country, language, date range, media type, platforms, sort order) are extracted automatically
5. 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:

1. 🔗 All URLAds are processed first (each URL uses its own filters from the URL)
2. 🏢 Then searchAdvertisers are resolved and scraped (using the input schema filters)
3. 🔍 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

---