# Facebook Search Scraper (`alien_force/facebook-search-scraper`) Actor

Powerful Facebook search that scrapes and searches posts, pages, and profiles by keyword. Get detailed info like author, engagement metrics, images, videos. Ideal for research, monitoring, and analysis.

- **URL**: https://apify.com/alien\_force/facebook-search-scraper.md
- **Developed by:** [Alien Force](https://apify.com/alien_force) (community)
- **Categories:** Social media, Videos
- **Stats:** 1,814 total users, 71 monthly users, 100.0% runs succeeded, 40 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$30.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 📘 Facebook Search Scraper

**Facebook Search Scraper** is a powerful tool that enables you to search and extract public content from Facebook based on a keyword. You can use it to discover posts, pages, or people matching your search criteria — ideal for research, monitoring, or competitive analysis.

***

### 🚀 Key Features

- 🔎 Search Facebook by **keyword**
- 📝 Fetch public **posts**, **pages**, or **people**
- 📅 Optional filter to sort posts by recency
- 🎞 Optional: fetch **only Reels** (applies to `search_type: "posts"`; switches to Facebook’s Videos/Reels search tab)
- 📅 New: You can now filter posts by a start date and end date to retrieve content within a specific range. If no range is provided, you can instead use since with options like 1d, 7d, or 30d, or simply leave these attributes empty if you don’t want to apply a time interval.
- 📊 Get engagement data: likes, shares, comments, views
- 👤 Author details (name, profile picture, ID)
- 🖼 Image, video, and post content extraction
- 📍 Filter results by **location** using either a numeric Facebook location/page ID or a human-readable place name (applies to posts, pages, and people)

***

### 📥 Input Schema

| Field                    | Type      | Description                                                      |
| ------------------------ | --------- | ---------------------------------------------------------------- |
| `search_type`            | `string`  | One of `"posts"`, `"pages"`, or `"people"`                       |
| `keyword`                | `string`  | The search term to use                                           |
| `filter_by_recent_posts` | `boolean` | If true, filters to most recent posts                            |
| `results_limit`          | `number`  | Maximum number of search results to return                       |
| `min_wait_time_in_sec`   | `number`  | Minimum wait time between requests (to avoid rate limiting)      |
| `max_wait_time_in_sec`   | `number`  | Maximum wait time between requests                               |
| `cookies`                | `array`   | Optional cookies for authenticated access                        |
| `fetch_reaction_map`     | `boolean` | When enabled, fetches reaction breakdown for video posts only. Regular posts always include reaction data regardless of this setting. |
| `follow_post_scraping`   | `boolean` | When enabled, each search result is followed by a per-post scrape for richer/more reliable data. Defaults to `true`. Auto-forced to `true` when `only_reels` is enabled. |
| `start_date`             | `string`  | Optional filter to specify the start date for posts (YYYY-MM-DD) |
| `end_date`               | `string`  | Optional filter to specify the end date for posts (YYYY-MM-DD)   |
| `since`                  | `string`  | Optional relative time window; one of `"1d"`, `"7d"`, or `"30d"`. overrides `start_date`/`end_date` if provided |
| `location`               | `string`  | Optional location filter. Accepts either a 10–20 digit Facebook place/page ID, or a place name. Preferred string format is "City, Country" (e.g., "Berlin, Germany"). Names are auto-resolved to the closest match via Facebook's place typeahead. Applies to `posts`, `pages`, and `people`. |
| `only_reels`             | `boolean` | When enabled, fetches results from Facebook’s **Reels/Videos** search tab (applies to `search_type: "posts"`). |

#### 📍 Location Filtering

- **What you can pass**:
  - **Numeric ID**: a 10–20 digit Facebook location/page ID. This is treated as an exact match.
  - **Place name**: a human-readable place string. Preferred format is "City, Country" (e.g., "Berlin, Germany", "Cairo, Egypt"). The scraper resolves this to the closest Facebook place using a typeahead lookup.
- **How it works internally**:
  - If `location` looks like a numeric ID, it is used directly.
  - If `location` is a name, it is resolved to an ID first. If no place is found, the location filter is skipped.
- **Applies to all search types**:
  - `posts` → adds a `location` filter
  - `pages` → adds a `filter_pages_location` filter
  - `people` → adds a `users_location` filter

##### 💡 Examples

```json
{
  "search_type": "posts",
  "keyword": "coffee",
  "results_limit": 10,
  "location": "106377336067638"  // numeric Facebook location/page ID
}
```

```json
{
  "search_type": "people",
  "keyword": "john",
  "results_limit": 10,
  "location": "New York, United States"  // preferred City, Country string; will be resolved to an ID
}
```

#### 📥 Example Input

```json
{
    "search_type": "posts",
    "keyword": "iron man",
    "filter_by_recent_posts": false,
    "results_limit": 10,
    "min_wait_time_in_sec": 1,
    "max_wait_time_in_sec": 4,
    "cookies": [],
    "fetch_reaction_map": false,
    "follow_post_scraping": true,
    "only_reels": false,
    "start_date": "2022-01-01",
    "end_date": "2022-12-31",
    "since": "1d", // this will override start_date and end_date
    "location": "Berlin, Germany",  // preferred City, Country string, or use a numeric Facebook ID
    "proxyConfiguration": {
        "useApifyProxy": true
    }
}
```

#### 📤 Example Output (Posts Type)

```json
[
    {
        "author": null,
        "post_id": "1404675087714921",
        "action_id": "ZmVlZGJhY2s6ODAzOTQ3OTc5MzQxMTg1",
        "text": "Peaky blinders in public 💀 #reaction #reel #cillianmurphy #peakyblinder #thomasshelby #peakyblinders",
        "create_time": 1767128233000,
        "post_url": "https://www.facebook.com/reel/1404675087714921",
        "like_count": 173,
        "comment_count": 2,
        "share_count": 5,
        "view_count": 2000,
        "reaction_map": [],
        "play_count": 2000,
        "image_list": [],
        "video_list": [
            "https://video.fcai20-5.fna.fbcdn.net/o1/v/t2/f2/m366/..."
        ],
        "video_cover_image": [
            "https://scontent.fcai20-6.fna.fbcdn.net/v/t15.5256-10/..."
        ],
        "durationInSec": [23.59],
        "type": "video",
        "author_username": "Felix Casilas",
        "author_user_id": "100091779716457",
        "author_profile_url": "https://www.facebook.com/people/Felix-Casilas/100091779716457/",
        "author_avatar": "https://scontent.fcai20-3.fna.fbcdn.net/v/t39.30808-1/..."
    }
]
```

**Note:** The `reaction_map` field contains reaction breakdown data when `fetch_reaction_map` is enabled. It is an array of objects with `name`, `count`, and `parsed_count` properties. Example:

```json
{
    "reaction_map": [
        {
            "name": "Like",
            "count": 188,
            "parsed_count": "188"
        },
        {
            "name": "Love",
            "count": 33,
            "parsed_count": "33"
        },
        {
            "name": "Care",
            "count": 1,
            "parsed_count": "1"
        }
    ]
}
```

#### 📤 Example Output (Pages and People Type)

```json
[
    {
        "input": "Google",
        "id": "100069202816629",
        "id_v2": "100069202816629",
        "name": "Google Cloud",
        "profile_url": "https://www.facebook.com/GoogleCloudIN",
        "profile_picture": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.30808-1...",
        "is_verified": true,
        "info": "Welcome to the official Google Cloud..."
    }
]
```

# Actor input Schema

## `cookies` (type: `array`):

1. Install the Cookie-Editor Chrome extension.
2. Log in to your Facebook account.
3. Open the Cookie-Editor extension and export cookies as JSON for facebook.com.
4. Paste the exported cookie contents here.

## `search_type` (type: `string`):

Select what search type to work with.

## `keyword` (type: `string`):

Provide a keyword to search in Facebook.

## `filter_by_recent_posts` (type: `boolean`):

When selected, newer posts will be fetched first. (applied only with search type 'posts')

## `fetch_reaction_map` (type: `boolean`):

When turned on, reaction map is fetched for each post of type `video` only. Regular post items are always fetched regardless of this setting.

## `follow_post_scraping` (type: `boolean`):

When turned on, SEARCH posts results are followed by a per-post scrape for more reliable data. Required (and force-enabled) when `only_reels` is true.

## `since` (type: `string`):

Filter by time interval. This attribute will override the `start_date` and `end_date` filters

## `start_date` (type: `string`):

Select absolute date in format YYYY-MM-DD.
This attribute will override the filter\_by\_recent\_posts value

## `end_date` (type: `string`):

Select absolute date in format YYYY-MM-DD.
This attribute will override the filter\_by\_recent\_posts value

## `location` (type: `string`):

Filter results by location for all search types (posts, pages, people). Accepts either a 10-20 digit Facebook place/page ID for an exact match, or a place name (e.g., "New York, NY") which will be resolved to the closest match via Facebook's place typeahead. If the name cannot be resolved, the location filter is skipped.

## `only_reels` (type: `boolean`):

When selected, only reels will be fetched.

## `results_limit` (type: `integer`):

Limit number of results, minimum is 10 results

## `min_wait_time_in_sec` (type: `integer`):

Minimum seconds to wait for each cursor.

## `max_wait_time_in_sec` (type: `integer`):

Maximum seconds to wait for each cursor.

## `proxyConfiguration` (type: `object`):

Configure proxies to be used by the crawler.

## Actor input object example

```json
{
  "cookies": [],
  "search_type": "posts",
  "keyword": "BBC",
  "filter_by_recent_posts": false,
  "fetch_reaction_map": false,
  "follow_post_scraping": true,
  "since": "all_times",
  "only_reels": false,
  "results_limit": 10,
  "min_wait_time_in_sec": 1,
  "max_wait_time_in_sec": 4,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cookies": [],
    "search_type": "posts",
    "keyword": "BBC",
    "filter_by_recent_posts": false,
    "fetch_reaction_map": false,
    "follow_post_scraping": true,
    "only_reels": false,
    "results_limit": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("alien_force/facebook-search-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cookies": [],
    "search_type": "posts",
    "keyword": "BBC",
    "filter_by_recent_posts": False,
    "fetch_reaction_map": False,
    "follow_post_scraping": True,
    "only_reels": False,
    "results_limit": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("alien_force/facebook-search-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cookies": [],
  "search_type": "posts",
  "keyword": "BBC",
  "filter_by_recent_posts": false,
  "fetch_reaction_map": false,
  "follow_post_scraping": true,
  "only_reels": false,
  "results_limit": 10
}' |
apify call alien_force/facebook-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=alien_force/facebook-search-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/blf62maenLRO8Rsfv/builds/aWEJM603fP0uIcNEI/openapi.json