🔍 Facebook Ads Scraper Pro - Ad Library Intelligence

Extract comprehensive data from Facebook's Ad Library with real-time streaming, advanced filtering, and standby mode support.

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

💎 Pricing Tiers - Choose Your Plan

FREE TIER ✅

Get started with no upfront cost

Included:

✅ Full access to Facebook Ad Library data
✅ 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)

Trade-offs:

⚠️ Shared proxy infrastructure
⚠️ Occasional connection interruptions
⚠️ Best for small to medium projects (< 500 ads)

PAID TIER ⭐ RECOMMENDED FOR PRODUCTION

Upgrade for enterprise-grade reliability

All Free Tier features PLUS:

🚀 Dedicated premium proxy - Your own reliable connection
🚀 No rate limiting - Unlimited continuous scraping
🚀 90% 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?

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

📊 Feature Comparison

Feature	FREE	PAID ⭐
Ads per query	Up to 100	∞+
Rate limiting	Yes	No
Connection stability	Occasional issues	Always stable
Best for	Testing & small projects	Agencies & production
Support	Standard	Priority

🚀 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 in Standby Mode (Recommended) ⭐

Perfect for: Real-time applications, multiple requests, APIs, instant responses

# Actor automatically runs in standby mode
# Access via: https://dz-omar--facebook-ads-scraper-pro.apify.actor

Standby Mode Advantages:

Feature	Batch Mode	Standby Mode
Cold Start	8-15 seconds	0 seconds ⚡
Response Time	Slow (start overhead)	Instant
Best For	Scheduled tasks	Real-time apps
Concurrent Requests	Sequential	Parallel ∞
Always Running	No	Yes (pre-warmed)
Cost	Lower	Higher (always on)
Ideal Use	Nightly scrapes	Live dashboards

Real-World Comparison:

Scenario	Batch Mode	Standby Mode
Track competitor ads daily	✅ Good	⭐ Excellent
Build a SaaS dashboard	⚠️ Too slow	✅ Perfect
One-time research project	✅ Best	Overkill
API for other apps	❌ Not viable	✅ Ideal
Monitor 50 keywords live	❌ No	✅ Yes

Example: Why Standby Mode is Better for Real-Time Dashboards

Imagine you're building a competitor monitoring dashboard that updates live:

Without Standby (Batch Mode):

User clicks "Refresh"
  ↓
Wait 10 seconds for cold start
  ↓
Wait 30 seconds for results
  ↓
40 seconds total ❌ (User closes browser)

With Standby Mode:

User clicks "Refresh"
  ↓
Results instantly (pre-warmed)
  ↓
2 seconds total ✅ (User stays engaged)

📡 API Endpoints

POST / - Custom Scraping with Real-Time Streaming

Send search parameters and receive ad data in real-time NDJSON stream.

Full Example:

curl -X POST https://dz-omar--facebook-ads-scraper-pro.apify.actor \
  -H "Content-Type: application/json" \
  -d '{
    "searchQueries": ["nike", "adidas"],
    "searchAdvertisers": ["Nike Football", "15087023444"],
    "maxResultsPerQuery": 100,
    "countries": ["US"],
    "contentLanguages": ["en"],
    "activeStatus": "ACTIVE",
    "adType": "ALL",
    "mediaType": "IMAGE",
    "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
    "sortBy": "SORT_BY_TOTAL_IMPRESSIONS",
    "startDate": "2024-01-01",
    "endDate": "2025-01-31"
  }'

Minimal Example:

curl -X POST https://dz-omar--facebook-ads-scraper-pro.apify.actor \
  -H "Content-Type: application/json" \
  -d '{"searchQueries": ["nike"]}'

Advertiser-Only Search:

curl -X POST https://dz-omar--facebook-ads-scraper-pro.apify.actor \
  -H "Content-Type: application/json" \
  -d '{"searchAdvertisers": ["Nike"], "maxResultsPerQuery": 200}'

Save Results to File:

curl -X POST https://dz-omar--facebook-ads-scraper-pro.apify.actor \
  -H "Content-Type: application/json" \
  -d '{"searchQueries": ["nike"]}' \
  > results.ndjson

📋 Input Parameters

Parameter	Type	Default	Min	Max	Description
`searchQueries`	array	`[]`	0	∞	Keywords to search (e.g., `["nike", "adidas"]`)
`searchAdvertisers`	array	`[]`	0	∞	Advertiser names or page IDs
`maxResultsPerQuery`	integer	`10`	10	∞	Max ads per query/advertiser
`batchSize`	integer	`30`	10	100	Ads per batch request
`countries`	array/string	`["ALL"]`	-	-	Country codes (e.g., `["US", "GB", "FR"]`)
`contentLanguages`	array	`[]`	0	∞	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	`[]`	0	6	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)

⚠️ Important: Input Does Not Exist

At least one of these MUST be provided:

searchQueries - Contains search keywords (required if no advertisers)
searchAdvertisers - Contains advertiser names/page IDs (required if no queries)

Invalid Input Examples (Will Fail):

{
  "maxResultsPerQuery": 50
}

❌ Error: "Must provide either searchQueries or searchAdvertisers"

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

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

{
  "countries": ["US"],
  "activeStatus": "ACTIVE"
}

❌ Error: "Input does not exist - missing searchQueries or searchAdvertisers"

Valid Input Examples:

{
  "searchQueries": ["nike"]
}

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

{
  "searchAdvertisers": ["15087023444"]
}

✅ Valid - Searches all ads from page ID

{
  "searchQueries": ["marketing"],
  "searchAdvertisers": ["Nike", "Apple"],
  "maxResultsPerQuery": 100,
  "countries": ["US"]
}

✅ Valid - Searches keywords in ads from specific advertisers

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

📤 Response Format (NDJSON Stream)

Each line is a JSON object representing real-time data. Process line-by-line as they arrive:

Log Messages

{"type":"log","level":"info","message":"🔍 Processing 2 keyword queries","timestamp":"2026-01-25T23:14:09Z"}
{"type":"log","level":"success","message":"📤 Sent batch: 30 ads for \"nike\"","timestamp":"2026-01-25T23:14:15Z"}
{"type":"log","level":"error","message":"❌ Query failed: No ads found","timestamp":"2026-01-25T23:14:20Z"}

Ad Batches (Real-Time)

{
  "type":"batch",
  "source":"keyword_query",
  "query":"nike",
  "batchSize":30,
  "ads":[{ad_object}, {ad_object}, ...],
  "timestamp":"2026-01-25T23:14:15Z"
}

Completion Events

{"type":"query_complete","query":"nike","totalAds":100,"timestamp":"2026-01-25T23:14:30Z"}
{"type":"advertiser_complete","advertiser":"Nike","totalAds":50,"timestamp":"2026-01-25T23:14:35Z"}

Error Events

{"type":"query_error","query":"test","error":"No ads found","timestamp":"2026-01-25T23:14:25Z"}
{"type":"advertiser_error","advertiser":"invalid","error":"Could not resolve advertiser","timestamp":"2026-01-25T23:14:40Z"}

Summary Statistics

{
  "type":"summary",
  "stats":{
    "queries":{
      "total":2,
      "success":2,
      "failed":0,
      "ads":150
    },
    "advertisers":{
      "total":1,
      "success":1,
      "failed":0,
      "ads":50
    }
  },
  "timestamp":"2026-01-25T23:14:40Z"
}

Completion

{"type":"complete","timestamp":"2026-01-25T23:14:45Z"}

📊 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"
}

🎯 Search Modes Explained

1. 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

2. Advertiser Search

Search ads from specific Facebook pages:

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

Use Case: Monitor what a specific brand/company is advertising

3. Combined Search

Both keywords and advertisers in one request:

{
  "searchQueries": ["marketing"],
  "searchAdvertisers": ["Nike", "Apple"],
  "maxResultsPerQuery": 50
}

Use Case: Find specific keywords in ads from selected companies

🌍 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

🔄 Standby Mode Deep Dive

What is Standby Mode?

Standby Mode keeps the actor running 24/7 as an HTTP API server, ready to handle requests instantly without startup delays.

Traditional Batch Mode:

Request → Start Actor (8-15s) → Process → Stop Actor

Standby Mode:

Request → Instant Response (pre-warmed instance)

Why Choose Standby Mode?

Use Case	Batch Mode	Standby Mode
Nightly automated scrape	✅ Best choice	Overkill
Live competitor dashboard	❌ Too slow	✅ Essential
API for external apps	❌ Not viable	✅ Perfect
Real-time alerts	❌ No	✅ Yes
Webhook integrations	❌ Doesn't work	✅ Works great
Mobile app backend	❌ No	✅ Great
Research project	✅ Good	Expensive

Technical Advantages

Cold Start Elimination:

Batch: 10-15 seconds to start
Standby: 0 seconds (instant)
Difference: 10-15 seconds per request saved

Scalability:

Batch: One request at a time
Standby: Handle 100+ concurrent requests
Difference: 100x throughput

User Experience:

Batch: User waits for response
Standby: Instant results
Difference: User stays engaged

Example: Competitor Monitoring Dashboard

Scenario: Build a live dashboard monitoring Nike, Adidas, and Puma ads

With Batch Mode:

Dashboard loads
  ↓
User clicks "Nike" tab
  ↓
API call to scraper
  ↓
Wait 10 seconds (cold start) ❌
  ↓
Wait 20 seconds (scraping) ❌
  ↓
Display results
  ↓
Total time: 30 seconds (user frustrated)

With Standby Mode:

Dashboard loads (scraper pre-warmed)
  ↓
User clicks "Nike" tab
  ↓
API call to scraper
  ↓
Results instantly ✅
  ↓
Display results
  ↓
Total time: 2 seconds (user delighted)

How to Access Standby Mode

Automatic Access: Simply use the actor URL directly:

https://dz-omar--facebook-ads-scraper-pro.apify.actor

No Configuration Needed:

Instance is always running
Ready 24/7
No startup delay
Just send HTTP requests

Direct Integration Example:

Your application can make direct API calls:

POST https://dz-omar--facebook-ads-scraper-pro.apify.actor
Content-Type: application/json

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

Standby Mode Pricing

Higher Cost: Actor runs continuously
Break-even Point: ~3-4 requests per day
Best For: High-frequency usage patterns
Not Ideal For: Low-frequency, scheduled tasks

Cost Comparison (Example):

100 daily requests
- Batch mode: 100 starts × 30 sec = 50 min/day = $$
- Standby mode: Always on = $ (often cheaper!)

Standby Mode Limitations

Maximum continuous run: ~30 minutes idle timeout
Reconnect is automatic if disconnected
Not suitable for very low-frequency usage
Higher base cost even if no requests

Standby Mode Best Practices

Keep Connections Alive: Send heartbeat requests periodically
Handle Reconnections: Implement retry logic on client side
Batch Related Requests: Send multiple queries in one request when possible
Monitor Performance: Track response times and errors
Set Reasonable Limits: Don't request 10,000 ads if you need 100

Aspect	Details
Requests	No hard limit, respects Facebook's rate limits
Batch Size	Default 30 ads, configurable 10-100
Results per Query	1-10,000 ads per query
Concurrent Requests	Unlimited (standby mode scales automatically)
Response Time	Real-time streaming - results as they arrive
Memory Usage	No limits - stream 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

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

Connection Issues (Free Tier)

Intermittent failures: Consider upgrading to Paid tier 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 Paid

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 tier limits: Consider Paid tier for 1000+ ads per query
Better results: Upgrade to Paid tier for 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

📞 Support

Get Help

🌐 Website: flowextractapi.com
📧 Email: flowextractapi@outlook.com
🙋 Apify Profile: dz_omar
💬 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
Latest commit History 2 Commits
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation