# Facebook Keyword Search Scraper (`datafinch/facebook-keyword-search-scraper`) Actor

Facebook posts scraper by keyword: get text, author, date, reactions, comments, shares and video views from public Facebook posts. No login or cookies. Ideal for brand monitoring and competitor tracking. Pay only for posts you receive.

- **URL**: https://apify.com/datafinch/facebook-keyword-search-scraper.md
- **Developed by:** [Datafinch](https://apify.com/datafinch) (community)
- **Stats:** 7 total users, 3 monthly users, 98.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.65 / 1,000 posts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Facebook Keyword Search Scraper

Search public Facebook posts by keyword and get clean, structured data: full post text, author, date, total reactions, comments, shares, video views, media and links.

- **No Facebook account needed.** No login, password or cookies.
- **Public content only.** Returns what any logged-out visitor can see.
- **Many keywords in one run.** Keywords are searched in parallel.
- **Optional filters.** Newest posts first, last 24 hours / 7 days / 30 days, or a custom date range.
- **Simple pricing.** You pay only for posts you receive.

***

### What it does

1. You enter one or more keywords (brands, products, topics, hashtags).
2. The Actor searches Facebook posts for each keyword.
3. It collects public posts up to your limit per keyword and removes duplicates.
4. Every post is saved to the dataset, ready to export as JSON, CSV or Excel, or to use through the API, n8n, Make or Zapier.

***

### Use cases

- **Brand monitoring:** see what is being posted about your brand or products.
- **Competitor tracking:** follow posts mentioning competitors and compare engagement.
- **Campaign and hashtag tracking:** collect posts for a campaign keyword or hashtag.
- **Market research:** find public conversations about a topic, product or industry.
- **Influencer and page discovery:** find active pages and authors posting about a subject.

***

### Input

```json
{
    "queries": ["electric cars", "EV charging"],
    "maxResultsPerQuery": 50
}
```

| Field | Default | Description |
|---|---|---|
| **Search keywords** (`queries`) | required | Keywords or phrases to search. Each one is searched separately. Up to 100 per run. |
| **Maximum posts per keyword** (`maxResultsPerQuery`) | `100` | Upper limit of posts for each keyword (1-5000). |
| **Strict keyword filter** (`keywordFilter`) | `false` | Keep only posts whose text contains the keyword. |
| **Sort results** (`sortBy`) | `relevance` | `recent` = newest posts first. See Filters. |
| **Posted within** (`postedWithin`) | `any` | Keep only posts from the last 24 hours, 7, 30, 90 days or 12 months. |
| **Posted on or after / before** (`postedAfter`, `postedBefore`) | empty | Custom date range, `YYYY-MM-DD`. |
| **Search type** (`searchType`) | `posts` | Type of results. |
| **Proxy configuration** (`proxyConfiguration`) | Residential | Residential is recommended. |
| **Parallel keywords** (`maxConcurrency`) | `3` | How many keywords are searched at the same time (1-5). |

#### Tips

- **Put all your keywords in one run.** One run with 5 keywords is faster and cheaper than 5 runs with 1 keyword each.
- **The limit is per keyword.** 2 keywords x 50 = up to 100 posts. It is a maximum, not a guarantee: if Facebook shows fewer public posts for a keyword, you get what is available.
- **Strict keyword filter:** Facebook also matches hashtags, page names and link previews. Turn this on if you only want posts that mention the keyword in their text.
- **No quotes needed.** Use `electric cars`, not `"electric cars"`.

***

### Filters (optional)

| Field | Values | What it does |
|---|---|---|
| **Sort results** (`sortBy`) | `relevance` (default), `recent` | `recent` asks Facebook for the newest posts first |
| **Posted within** (`postedWithin`) | `any` (default), `24h`, `7d`, `30d`, `90d`, `365d` | Keeps only posts from that period |
| **Posted on or after** (`postedAfter`) | `YYYY-MM-DD` | Start date (ignored if Posted within is set) |
| **Posted on or before** (`postedBefore`) | `YYYY-MM-DD` | End date |

Example, newest posts from the last 7 days:

```json
{ "queries": ["Tesla"], "maxResultsPerQuery": 50, "sortBy": "recent", "postedWithin": "7d" }
```

- Date filters are always applied exactly on the post date, so every post you receive is inside your range.
- **Most recent first** shows about 50-70 of the newest posts per keyword (Facebook's limit for public search). For busy keywords that covers roughly the last day, so a higher limit may not be reached. The order is newest first in general, not strictly by minute; sort by `timestamp` if you need an exact order.
- With filters on, a keyword stops early when no more matching posts are found, so a run may return fewer posts than the limit. You pay only for posts you receive.
- **Daily monitoring tip:** run once a day with `sortBy: recent` and `postedWithin: 24h`.

***

### Output

One dataset item per post:

```json
{
    "type": "post",
    "postId": "1610706737767863",
    "authorName": "Example Page",
    "url": "https://www.facebook.com/...",
    "profileUrl": "https://www.facebook.com/...",
    "description": "Full post text...",
    "snippet": "Short preview of the post text...",
    "timestamp": "2026-10-05T09:12:44.000Z",
    "likesCount": 5646,
    "commentsCount": 285,
    "sharesCount": 25,
    "viewsCount": 166177,
    "mediaType": "video",
    "images": ["https://..."],
    "attachmentUrl": "https://example.com/...",
    "query": "electric cars",
    "searchType": "posts",
    "position": 1,
    "scrapedAt": "2026-10-07T10:35:00.000Z"
}
```

| Field | Meaning |
|---|---|
| `postId` | Facebook post ID |
| `authorName`, `profileUrl` | Who published the post (page or profile) |
| `url` | Link to the post |
| `description` | Full post text |
| `snippet` | First 300 characters of the text |
| `timestamp` | When the post was published (UTC) |
| `likesCount` | Total reactions (like, love, haha, etc. combined) |
| `commentsCount` | Total comments |
| `sharesCount` | Total shares |
| `viewsCount` | Video views (videos only) |
| `mediaType` | `text`, `photo`, `video`, `link`, ... |
| `images` | Image links in the post |
| `attachmentTitle`, `attachmentUrl` | Shared link, if any |
| `query` | Keyword that found this post |
| `position` | Order of the post within that keyword's results |
| `scrapedAt` | When the post was collected |

- A count is `null` when Facebook does not show it publicly. `0` means Facebook reported zero.
- Fields with no data are left out.
- Posts from different keywords can be mixed in the dataset. Use `query` to group them.

***

### Duplicates

- The same post (same `postId`) is returned only once per keyword.
- Different posts are always kept, even from the same author.
- If two keywords find the same post, it appears once under each keyword.

***

### Using it with the API or n8n

**HTTP Request** (runs the Actor and returns the posts in one call):

- **Method:** `POST`
- **URL:** `https://api.apify.com/v2/acts/datafinch~facebook-keyword-search-scraper/run-sync-get-dataset-items?timeout=300`
- **Header:** `Authorization: Bearer <YOUR_APIFY_TOKEN>`
- **Body (JSON):**

```json
{
    "queries": ["electric cars", "EV charging"],
    "maxResultsPerQuery": 50
}
```

The call waits up to 5 minutes. For larger runs, start the run asynchronously and fetch the dataset when it finishes (the Apify node in n8n does this with "wait for finish").

To get only new posts, use the filters in the input instead of filtering afterwards, for example `"sortBy": "recent", "postedWithin": "24h"`.

***

### FAQ

**Why did I get fewer posts than my limit?**
Facebook shows a limited number of results to logged-out visitors. Many keywords return roughly 60-100 posts, even with a higher limit.

**Why are results slightly different between runs?**
Facebook's ranking changes over time, so the same keyword can return a slightly different set of posts.

**Are the numbers exact?**
Reactions, comments, shares and views are the exact numbers Facebook provides, not rounded values like "1.2K".

**Does it work for private groups or profiles?**
No. Only public content visible without logging in is collected.

**Something isn't working.**
Please open an issue in the Issues tab with your run link. We usually respond quickly.

# Actor input Schema

## `queries` (type: `array`):

One or more keywords or phrases to search on Facebook, e.g. a brand, product or topic. Each keyword is searched separately. Up to 100 keywords per run.

## `maxResultsPerQuery` (type: `integer`):

Upper limit of posts collected for each keyword. The run stops earlier if Facebook shows fewer public posts.

## `keywordFilter` (type: `boolean`):

Keep only posts whose text contains the keyword. Off by default, because Facebook also matches hashtags, page names and link previews.

## `sortBy` (type: `string`):

Most relevant is Facebook's default order. Most recent first is best for monitoring new posts; Facebook then shows about 50-70 of the newest posts per keyword.

## `postedWithin` (type: `string`):

Keep only posts published in this period. Leave on 'Any time' for no date limit.

## `postedAfter` (type: `string`):

Optional start date, format YYYY-MM-DD (e.g. 2026-10-01). Ignored if 'Posted within' is set.

## `postedBefore` (type: `string`):

Optional end date, format YYYY-MM-DD (e.g. 2026-10-31).

## `searchType` (type: `string`):

Type of Facebook results to collect.

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

Residential proxy is recommended. Facebook limits searches from datacenter IPs; if you choose datacenter, the Actor switches to residential automatically when blocked.

## `maxConcurrency` (type: `integer`):

How many keywords are searched at the same time. 3 is a good default.

## Actor input object example

```json
{
  "queries": [
    "electric cars"
  ],
  "maxResultsPerQuery": 20,
  "keywordFilter": false,
  "sortBy": "relevance",
  "postedWithin": "any",
  "searchType": "posts",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "maxConcurrency": 3
}
```

# Actor output Schema

## `posts` (type: `string`):

No description

## `allFields` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "queries": [
        "electric cars"
    ],
    "maxResultsPerQuery": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("datafinch/facebook-keyword-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 = {
    "queries": ["electric cars"],
    "maxResultsPerQuery": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

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

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

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

```

## CLI example

```bash
echo '{
  "queries": [
    "electric cars"
  ],
  "maxResultsPerQuery": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call datafinch/facebook-keyword-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datafinch/facebook-keyword-search-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kPkIoDx8Zl0g6Xl9F/builds/yxrgrqdKwbZlFHKzv/openapi.json