Facebook Event Search Scraper

A powerful Apify Actor designed to scrape Facebook Events by search keywords. This actor enables you to search for events using keywords, extract comprehensive event metadata, and save results in a structured format.

Features

• 🔍 Keyword-based Search: Search Facebook Events using any keywords (e.g., "comedy", "music", "tech conference")
• ⚡ High Performance: Asynchronous processing with aiohttp for fast data collection
• 🛡️ Smart Proxy Management: Automatic proxy fallback to handle blocks gracefully
  • Starts with no proxy (direct connection)
  • Falls back to datacenter proxy if blocked
  • Falls back to residential proxy if still blocked
  • Retries 3 times with residential proxy before giving up
• 💾 Live Saving: Results saved immediately as they're scraped
• 📊 Rich Metadata: Extract event ID, title, URL, type, and scrape timestamp
• 🔄 Automatic Pagination: Handles pagination automatically to collect large datasets
• 📝 Detailed Logging: Real-time Apify logs to track progress and troubleshoot issues
• 🎯 Reliable: Built-in retry logic and error handling for robust operation

Input

Input Schema

{
  "startUrls": [
    "comedy",
    "music",
    "tech conference"
  ],
  "maxEvents": 50,
  "sortOrder": "relevance",
  "maxComments": 0,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Input Parameters

Parameter	Type	Required	Default	Description
startUrls	array	✅ Yes	-	List of search keywords. Simply enter plain text keywords (e.g., "comedy", "football"). The actor automatically converts them to Facebook Event search URLs.
maxEvents	integer	❌ No	50	Maximum number of events to scrape per keyword. Range: 1-1000.
sortOrder	string	❌ No	"relevance"	Sort order for search results. Options: "relevance", "date" (currently not used by Facebook's API).
maxComments	integer	❌ No	0	Maximum number of comments to scrape per event (future feature). Range: 0-1000.
proxyConfiguration	object	❌ No	{"useApifyProxy": false}	Proxy configuration. By default, no proxy is used. If Facebook blocks requests, the actor automatically falls back to datacenter proxy, then residential proxy with 3 retries.

Input Examples

Example 1: Simple Keywords

{
  "startUrls": [
    "comedy",
    "music"
  ],
  "maxEvents": 50
}

Example 2: With Residential Proxy

{
  "startUrls": [
    "tech conference",
    "startup meetup",
    "networking event"
  ],
  "maxEvents": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Output

The actor saves results to the Apify dataset. Each event entry contains:

Output Schema

{
  "query": "comedy",
  "type": "search_event",
  "event_id": "123456789",
  "title": "Stand-Up Comedy Night",
  "url": "https://www.facebook.com/events/123456789/",
  "scrapedAt": "2025-11-05T12:30:45Z"
}

Output Fields

Field	Type	Description
query	string	The search keyword used to find this event
type	string	Event type, always "search_event"
event_id	string	Facebook Event ID
title	string	Event title/name
url	string	Direct link to the event on Facebook
scrapedAt	string	ISO 8601 timestamp when the event was scraped

How the Actor Works

1. Proxy Fallback Logic

The actor implements intelligent proxy fallback:

1. Start with NO PROXY (direct connection)
   ↓ (if blocked)
2. Fallback to DATACENTER PROXY
   ↓ (if blocked)
3. Fallback to RESIDENTIAL PROXY
   ↓ (if fails)
4. Retry 3 times with RESIDENTIAL PROXY
   ↓
5. Once switched to residential, use it for ALL remaining requests

All proxy events are clearly logged in the Apify console.

2. Scraping Process

For each keyword:
  1. Get Facebook doc_id and initial cursor
  2. Fetch events page by page (pagination)
  3. Extract event data (ID, title, URL)
  4. Save to dataset immediately (live saving)
  5. Continue until maxEvents reached or no more pages

3. Error Handling

• 3 retries for each network request
• 2-second delay between retries
• Automatic proxy fallback on blocks
• Graceful degradation - returns successfully scraped data even if some requests fail

Best Use Cases

• 📅 Event Discovery: Find events in your city or niche
• 📊 Market Research: Analyze event trends and topics
• 🔍 Competitive Analysis: Monitor competitors' events
• 📈 Trend Monitoring: Track popular event categories over time
• 🎯 Lead Generation: Find events in your target audience
• 📝 Content Curation: Collect events for event listing websites
• 🔬 Data Analysis: Gather event data for research and analytics

Performance

• Speed: Processes 50-100 events per minute (depends on proxy and Facebook's rate limits)
• Concurrency: Asynchronous requests for optimal performance
• Live Saving: Results available immediately, even if actor stops mid-run
• Pagination: Automatically handles pagination to collect all results

Proxy Recommendations

No Proxy (Default)

• Best for: Small-scale scraping (< 100 events)
• Risk: May get blocked by Facebook after a few requests

Datacenter Proxy

• Best for: Medium-scale scraping (100-500 events)
• Speed: Fast
• Cost: Low
• Risk: Moderate chance of blocks

Residential Proxy (Recommended)

• Best for: Large-scale scraping (> 500 events)
• Speed: Moderate
• Cost: Higher
• Risk: Lowest chance of blocks
• Reliability: Highest success rate

Troubleshooting

Issue: 0 Events Found

Possible Causes:

• Facebook is blocking your IP/proxy
• The search keyword returns no results on Facebook
• Facebook's API structure changed

Solutions:

1. Enable residential proxy in input
2. Try different search keywords
3. Check Apify logs for specific error messages

Issue: Actor Stops After a Few Events

Possible Causes:

• Facebook rate limiting
• Proxy getting blocked

Solutions:

1. Use residential proxy
2. Reduce maxEvents per keyword
3. Add more keywords instead of more events per keyword

Issue: Duplicate Events

Possible Causes:

• Running the actor multiple times without clearing the dataset

Solutions:

1. Clear the dataset before re-running
2. Use unique dataset for each run

Frequently Asked Questions

How does the proxy fallback work?

The actor starts with no proxy by default. If Facebook blocks a request:

1. First fallback: Automatically switches to datacenter proxy
2. Second fallback: If still blocked, switches to residential proxy
3. Residential retries: If residential proxy fails, retries 3 times before giving up
4. Persistence: Once switched to residential proxy, all remaining requests use it

Can I scrape private events?

No. This actor only scrapes publicly available events from Facebook Event search results. Private events and login-required content are not accessible.

What's the maximum number of events I can scrape?

You can scrape up to 1,000 events per keyword. You can run multiple keywords in a single actor run to collect more data.

How long does it take to scrape events?

Speed depends on:

• Number of keywords
• Maximum events per keyword
• Proxy type (residential is slower than datacenter)
• Facebook's response time

Typically, scraping 50 events per keyword takes 1-2 minutes.

Can I use this actor without a proxy?

Yes! By default, the actor uses no proxy. However, Facebook may block requests after scraping 10-20 events. For reliable large-scale scraping, use a residential proxy.

Support and Feedback

• Issues: Report bugs through the Apify platform
• Feature Requests: Suggest new features via Apify support
• Documentation: Check the Apify documentation for more details

Legal and Ethical Considerations

⚠️ Important:

• Public Data Only: This actor collects data only from publicly available Facebook Events
• No Private Content: Private events and password-protected content are not accessible
• Compliance: Ensure your use case complies with:
  • Facebook's Terms of Service
  • Data protection regulations (GDPR, CCPA, etc.)
  • Local laws regarding web scraping
  • Privacy and spam laws
• Rate Limiting: The actor includes delays and retry logic to avoid overwhelming Facebook's servers
• Responsible Use: Use this actor responsibly and ethically. Do not:
  • Scrape personal information without consent
  • Send unsolicited messages based on scraped data
  • Violate Facebook's Terms of Service
  • Use scraped data for spam or harassment

The end user is responsible for ensuring legal compliance with all applicable laws and regulations.

---

Version: 1.0
Last Updated: 2025
Actor Specification: 1