# Facebook Posts Backfill Scraper - Keyword History by Date (`topapi/facebook-posts-backfill-scraper`) Actor

Collect the public Facebook posts for your keywords over a past date range. The range is searched month by month, week by week or day by day, every search is read to its end, runs continue where the last one stopped, and a coverage report shows which windows are finished. No login or cookies.

- **URL**: https://apify.com/topapi/facebook-posts-backfill-scraper.md
- **Developed by:** [Top Api](https://apify.com/topapi) (community)
- **Categories:** Social media, Marketing, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 post scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

### What does Facebook Posts Backfill Scraper do?

**Facebook Posts Backfill Scraper** collects the public Facebook posts for your keywords over a past date range. You give it keywords and a range such as 2025-10-01 to 2026-09-30; it searches the range one window at a time (month, week or day), reads every search to its end, remembers where each one stopped, and reports which windows are finished. One row per post: full text, author Page or profile, publish date, reactions by type, comments, shares, video views, media and links.

Facebook Posts History - Facebook Keyword Backfill - Historical Facebook Posts by Date - Facebook Post Archive Scraper

- **Built for past periods:** Facebook serves a limited list of posts per search, so a year in one search returns a fraction of it. Searched by window, a quarter for one keyword took 3 searches and 47 pages on a test run and each of them ran to Facebook's end.
- **Every search is read to its end:** each search page is charged on its own, so a window where most posts fall outside your dates is still read through instead of being cut short.
- **Continues across runs:** every keyword and window keeps its position. Run the same input again and it carries on; a finished window is not read again, and a post delivered before is not delivered or charged twice.
- **Coverage report:** one line per keyword and window: finished or not, why it stopped, pages read and posts delivered in this run and over all runs.
- **Cost controls:** your run's maximum cost is never passed, and you can cap the pages read per keyword and window in a run.
- **No login, cookies or Facebook API key:** the actor reads only what Facebook shows a signed-out visitor.
- **Same rows as [Facebook Search Posts Scraper](https://apify.com/topapi/facebook-search-posts-scraper)**, plus `search_window`. Use that actor for quick searches, newest-first feeds and monitoring; use this one to fill in history.

### What data can you get for each Facebook post?

<table>
<tr>
<td>🔗 Post URL and id (`url`, `post_id`)</td>
<td>📝 Full text (`message`), hashtags, mentions</td>
<td>📅 Publish date (`timestamp`, `published_at`)</td>
</tr>
<tr>
<td>👤 Author id, name, URL, avatar, type</td>
<td>🏢 Business Page flag (`author.is_business_page`)</td>
<td>👍 Reactions total and by type (`reactions`)</td>
</tr>
<tr>
<td>💬 Comments and shares (`comments_count`, `reshare_count`)</td>
<td>▶️ Video views, duration, thumbnail, captions URL</td>
<td>🖼️ Photos and albums (`image`, `images`, `album_count`)</td>
</tr>
<tr>
<td>🌐 Outbound link with title, source, preview (`external_link`)</td>
<td>🔁 Shared post URL and author (`attached_post`)</td>
<td>👥 Public group id, name, URL (`group`)</td>
</tr>
<tr>
<td>📍 Tagged place (`location`)</td>
<td>🎯 Contains your keyword? (`matches_query`)</td>
<td>💬 Top comments, video files (details add-on)</td>
</tr>
</table>

On a 100-post test run for "coffee" every row had text, author, date, reactions, comments and shares; 73% carried an image, 47% came from public groups, 11% were videos (views on 10 of 11), 52% had hashtags and 91% contained the word "coffee".

### How to backfill Facebook posts by keyword with Facebook Posts Backfill Scraper

1. Open the actor and enter your keywords, one per line.
2. Set **From** and **To** with fixed dates (2025-10-01, 2026-09-30) and choose how to search the range: by month, week or day.
3. Set the run's maximum cost in the run options and, if you like, a page limit per keyword and window.
4. Start the run. When it ends, open the `COVERAGE` record to see what is finished.
5. Run the same input again until `allFinished` is `true`. Nothing read before is read or charged again.

### ⬇️ Input

| Field | Type | What it does |
|---|---|---|
| `searchQueries` | Array | Keywords, phrases, hashtags or Facebook search URLs, one per line. |
| `startDate` | String | Start of the range: `2025-10-01`, or relative (`3 months`, `1 year`). Empty = the last 30 days. |
| `endDate` | String | End of the range; the date includes that whole day. Empty = today. |
| `sliceBy` | String | `month` (default), `week`, `day` or `none`: the size of the windows the range is searched in. |
| `locationUid` | String | Facebook's numeric place id to restrict the search to posts tagged there. |
| `mustContainQuery` | Boolean | Keep only posts whose text contains the keyword. |
| `keywordFilter` | String | Keep only posts containing one of these words (comma = any of them). |
| `postType` | String | `all`, `photo`, `video`, `link` or `text`. |
| `postSource` | String | `all`, `groups`, `pages_and_profiles` or `business_pages`. |
| `minReactions` | Integer | Keep only posts with at least this many reactions. |
| `maxPagesPerSlice` | Integer | Search pages read for one keyword in one window during one run. 0 = until Facebook has no more. A search stopped here continues on the next run. |
| `maxPostsPerSlice` | Integer | Posts delivered for one keyword in one window. 0 = up to 1,000. |
| `maxItems` | Integer | Cap for the whole run. 0 = none. |
| `resumeStoreName` | String | Name of the job's memory (default `facebook-posts-backfill`). Give each separate job its own name. With the default name the memory is used only when `startDate` is a fixed date. Empty = no memory. |
| `includePostDetails` | Boolean | Adds top comments, video SD/HD files and the view count per post (paid add-on). |
| `compact` | Boolean | Core fields only, for AI agents and MCP clients. |
| `proxyConfiguration` | Object | Apify proxies by default; nothing to set. |

#### Input JSON

```json
{
  "searchQueries": ["coffee", "espresso machine"],
  "startDate": "2026-04-01",
  "endDate": "2026-06-30",
  "sliceBy": "month",
  "maxPagesPerSlice": 10,
  "resumeStoreName": "coffee-q2-2026"
}
```

#### Use fixed dates for a job that takes several runs

A window's saved position belongs to its exact dates. With `2025-10-01` to `2026-09-30` the windows are the same on every run and the job memory is on. A run with a relative start such as `3 months` is a one-off: it keeps no memory unless you set a `resumeStoreName` of your own, and then its first window moves a day every day and is read again from its first page (posts already delivered are still skipped and not charged).

#### Pick the window size by how busy the keyword is

Facebook ends a search after a limited number of pages (15 to 30 pages for a one-month window of one keyword on the test runs; a page holds 5-6 posts). A keyword with many posts a month gets more of them from weekly or daily windows; a quiet keyword is cheaper by month. Keep the same `sliceBy` for the whole job.

#### Filters do not make a run cheaper

`mustContainQuery`, `keywordFilter`, `postType`, `postSource` and `minReactions` are applied after a page is read. The page is charged either way; only the posts that pass are charged as posts.

### ⬆️ Output

Every post becomes one dataset item. One real row (trimmed):

```json
{
  "post_id": "1113407151220671",
  "type": "photo",
  "url": "https://www.facebook.com/greenhousecoffeebar21/posts/pfbid034DHRsirpdQQZBg84SYp3rXU1mD6xu1tMc8CsJ4gcgjiuWGeS2JMQnwV6eV81wfCBl",
  "message": "As we reflect on the last 4.5 years of Greenhouse we are filled with so much gratitude ...",
  "published_at": "2026-09-28T20:20:22.000Z",
  "author": { "id": "100076541894287", "name": "Greenhouse Coffee Bar", "url": "https://www.facebook.com/greenhousecoffeebar21", "type": "user", "is_business_page": false },
  "reactions_count": 48,
  "comments_count": 56,
  "reshare_count": 5,
  "reactions": { "like": 22, "love": 24, "care": 1, "haha": 0, "wow": 1, "sad": 0, "angry": 0 },
  "image": { "uri": "https://scontent-mia3-3.xx.fbcdn.net/v/t39.99422-6/...", "width": 526, "height": 701 },
  "is_group_post": false,
  "privacy": "Public",
  "hashtags": ["nationalcoffeeday"],
  "matches_query": true,
  "search_query": "coffee",
  "search_window": "2026-09-15/2026-09-30"
}
```

#### Facebook post fields

| Field | Type | What it is | Fill on the 100-post run |
|---|---|---|---|
| `post_id`, `url`, `story_id`, `comments_id` | string | Post id, permalink, story id, feedback id | 100% |
| `type` | string | `photo`, `album`, `video`, `link`, `marketplace`, `event`, `share` or `status` | 100% |
| `message` | string | Full text, never truncated (longest seen 3,160 characters) | 100% |
| `timestamp`, `published_at` | integer, ISO 8601 | Publish time | 100% |
| `author` | object | `id`, `name`, `url`, `profile_picture_url`, `type` (`page`, `user`, `anonymous`), `is_business_page` | 100% |
| `author_title` | string | Facebook's header line, e.g. "Iron Bloom Coffee Bar is in Elyria, OH." | 9% |
| `reactions_count`, `comments_count`, `reshare_count`, `engagement_count` | integer | Totals; engagement = reactions + comments + shares | 100% |
| `reactions` | object | `like`, `love`, `care`, `haha`, `wow`, `sad`, `angry`; an unlisted type is `0` when the listed ones add up to the total, else `null` | 97% |
| `video_view_count`, `video`, `video_id`, `video_thumbnail`, `video_duration_ms`, `video_captions_url` | mixed | Video posts only | 10-11% (every video post) |
| `video_files` | object | `video_sd_file`, `video_hd_file` - details add-on | 3 of 3 videos on the details run |
| `image`, `images`, `album_count`, `image_alt` | object, array | First image, every image of the post or album, accessibility caption | 73% / 81% |
| `external_url`, `external_link` | string, object | Outbound link (unwrapped) with title, description, source, preview image | 1% on "coffee", 7% across 307 mixed posts |
| `attached_post_url`, `attached_post` | string, object | The original post when this one is a share | 1% |
| `attachments` | array | Every attachment: kind, url, title, image, id | 92% |
| `is_group_post`, `group` | boolean, object | Public group `id`, `name`, `url` | 47% |
| `location` | object | Tagged place `id`, `name`, `url` | 2% on "coffee", 5% across 307 posts |
| `privacy` | string | `Public` or `Public group` | 100% |
| `hashtags`, `mentions` | array | Parsed from the text | 52% / 2% |
| `top_comments` | array | Up to ~10 public top comments: id, text, date, author, reactions - details add-on | 10 of 16 posts had one on the details run |
| `matches_query`, `search_query`, `search_window`, `sort`, `search_source`, `scraped_at` | mixed | Exact-match flag, the keyword and the date window (`from/to`) that produced the row | 100% |

#### The coverage report

Each run writes a `COVERAGE` record to its key-value store, and the job's memory keeps the same report across runs (record `coverage` in the store named by `resumeStoreName`).

```json
{
  "from": "2026-04-01", "to": "2026-06-30", "sliceBy": "month",
  "searches": 3, "finished": 3, "remaining": 0, "allFinished": true,
  "keywords": [{ "query": "China young man", "windows": 3, "finished": 3, "pages": 47, "delivered": 68 }],
  "slices": [
    { "query": "China young man", "window": "2026-05-01/2026-05-31", "finished": true, "stopReason": "exhausted",
      "pagesThisRun": 5, "deliveredThisRun": 4, "pagesAllRuns": 16, "deliveredAllRuns": 21, "runs": 2 }
  ]
}
```

`finished` is true only when Facebook had no further page for that keyword and window. `stopReason` for an unfinished search: `max_pages_per_slice` (your page limit for one run), `max_posts_per_query` (your post cap), `max_items`, `charge_limit` (the run's maximum cost), `run_time_limit` (the run's timeout), `page_limit` (303 pages in one run), `blocked` (Facebook refused or did not answer), `not_started` (the run ended before its turn). The `RUN_SUMMARY` record has the same per-search lines with `read`, `filtered` and `error`.

### How much does it cost to backfill Facebook posts?

Pay per event, no start fee:

| Event | Price |
|---|---:|
| Search page read | $0.004 |
| Post scraped | $0.0024 |
| Post details (optional add-on, per post that received them) | $0.001 |

A page is charged when it is read, whether or not its posts fall inside your window and filters. Apify platform usage (compute, proxy) is included. Measured on test runs (November 14, 2026):

| Job | Pages | Posts | Cost |
|---|---:|---:|---:|
| 1 keyword, 3 months by month, read to the end | 47 | 68 | $0.35 |
| 2 keywords, 4 weeks by week, 6 pages per search | 48 | 103 | $0.44 |
| 1 keyword, 3 days in the past (few posts exist) | 16 | 1 | $0.07 |

Set **Maximum cost per run** in the run options: the run stops there, keeps its positions and reports `charge_limit`. A run that reads nothing (every search finished earlier) charges nothing.

### Limits

- **Facebook decides how much a search returns.** A search ends when Facebook serves no further page; that is what `finished` means. Two runs of the same search can return different posts, because Facebook ranks per session. Smaller windows return more of a busy period.
- **Ranking:** posts come in Facebook's relevance order inside each window. Sort by `timestamp` for a timeline.
- **Relevance is Facebook's:** the search also returns loosely related posts. `matches_query` marks the exact matches; `mustContainQuery` keeps only those.
- **A saved position Facebook no longer accepts** makes that search start at its first page again. Its pages are charged again; its posts are not.
- **Up to 5,000 keyword-window searches per run** and 1,000 posts per keyword and window. Split larger jobs over several runs with the same memory name.
- **Reactions by type** are the types Facebook lists on the post; when they do not add up to the total, the unlisted types are `null`, not zero.
- **Post details** open each post's public page; comments are the top-level ones Facebook shows a visitor (0-10 per post), not the full thread. Use 256 MB with details.
- **Not available signed-out:** full comment threads, reactor lists, private groups, restricted-audience posts. Media and avatar URLs are signed CDN links that expire after a few hours.

### FAQ

#### How far back can Facebook Posts Backfill Scraper go?

As far as Facebook's public search serves posts for your keyword. Test runs delivered posts from October 2025 with a 2025 window. Older windows work the same way; how many posts Facebook still serves for them depends on the keyword.

#### How do I know a window was fully searched?

`finished: true` for that keyword and window in the `COVERAGE` record, and `allFinished: true` for the whole job.

#### What happens when a run hits its maximum cost or timeout?

It stops, saves every position and reports what is left. Start the same input again to continue.

#### Will I be charged twice for the same post?

No. Delivered posts are remembered per keyword in the job's memory, across runs and windows.

#### Can I get the newest posts or monitor a keyword with it?

Use [Facebook Search Posts Scraper](https://apify.com/topapi/facebook-search-posts-scraper) for newest-first searches and scheduled monitoring. This actor is for past periods.

#### Do I need a Facebook account, cookies or an API key?

No.

#### Can I use it with the Apify API, integrations or an MCP server?

Yes: it runs like any Apify actor from the API, schedules, webhooks, Make, Zapier, n8n and MCP clients. Run the default build (`latest`).

#### Your feedback

Found a bug or need a field? Open an issue on the actor's Issues tab.

# Actor input Schema

## `searchQueries` (type: `array`):

Keywords, phrases or hashtags, one per line, e.g. "coffee", "#blackfriday", "iPhone 17 battery". A Facebook search URL such as https://www.facebook.com/search/posts/?q=coffee also works. Each keyword is searched once per date window; every row carries search_query and search_window.

## `startDate` (type: `string`):

Start of the range. Use a fixed date (2025-10-01) for a job you will continue over several runs: the windows stay the same and the job memory is on. Relative values (3 months, 1 year) also work, as a one-off run. Empty = the last 30 days.

## `endDate` (type: `string`):

End of the range; a date includes that whole day (2026-09-30). Empty = today.

## `sliceBy` (type: `string`):

Facebook serves a limited list of posts per search, so a long range is searched one window at a time. Smaller windows find more posts and read more pages: a year by month is 12 searches per keyword, by week 53. Keep the same choice between runs of one job.

## `locationUid` (type: `string`):

Facebook's numeric id of a city or region to restrict the search to posts tagged there, e.g. 108424279189115 (New York, NY). Find it on facebook.com: search, open the city filter and copy the number at the end of the location page URL. Leave empty for a global search.

## `mustContainQuery` (type: `boolean`):

Keep only posts whose text contains the search query (case-insensitive). Facebook's search also returns related posts without the exact words; this makes the result strict. Measured on 307 posts: single words matched 94% (coffee, pizza), multi-word phrases far less ("hiring now apply" 0%, "zillow listing" 40%).

## `keywordFilter` (type: `string`):

Keep only posts whose text, author name or link title contain this word or phrase, case-insensitive, e.g. "recipe" or "discount, sale, promo" (comma = any of them). Leave empty for no filter.

## `postType` (type: `string`):

Keep only one kind of post. Marketplace listings and event posts count as 'photo' when they carry an image.

## `postSource` (type: `string`):

Where the post was published. Measured on 307 search results: 25% were public-group posts, 4% came from business Pages, the rest from profiles and creator pages.

## `minReactions` (type: `integer`):

Keep only posts with at least this many reactions, e.g. 100 to keep popular posts only. 0 = no minimum.

## `maxPagesPerSlice` (type: `integer`):

Search pages read for one keyword in one date window during one run (a page holds 5-6 posts). A search that stops here keeps its position and continues on the next run. 0 = read until Facebook has no more.

## `maxPostsPerSlice` (type: `integer`):

Posts delivered for one keyword in one date window. 0 = as many as Facebook serves, up to 1,000.

## `maxItems` (type: `integer`):

Hard cap for the whole run across all keywords and windows. 0 = no total cap.

## `resumeStoreName` (type: `string`):

Name of the key-value store that keeps each keyword and window's position, the posts already delivered and the coverage report. A search Facebook ran out of is not read again, and a post delivered by an earlier run is not delivered or charged twice. Give each separate job its own name (letters, digits, hyphens). With the default name the memory is used only when 'From' is a fixed date (2025-10-01); a run with a relative start (2 months) is a one-off unless you set a name of your own. Empty = no memory.

## `includePostDetails` (type: `boolean`):

Opens each post's public page and adds the top comments Facebook shows signed-out (up to about 10: text, author, date, reactions), the video SD/HD file URLs and the video view count. Charged as the post-details event only for posts that received details. About one extra request (0.8 MB) per post.

## `compact` (type: `boolean`):

Core fields only (post_id, type, url, message, published_at, author name/url/type, reactions, comments, shares, views, image, video, external_url, group, location, hashtags, search_query): about a fifth of the bytes, sized for AI agents and MCP clients.

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

Apify proxies by default: the session opens on the datacenter group and the search pages are read through Apify RESIDENTIAL (included in the price; no setting needed). Your own proxy URLs, if given, are used for everything.

## Actor input object example

```json
{
  "searchQueries": [
    "coffee"
  ],
  "startDate": "2 months",
  "sliceBy": "month",
  "mustContainQuery": false,
  "keywordFilter": "",
  "postType": "all",
  "postSource": "all",
  "minReactions": 0,
  "maxPagesPerSlice": 2,
  "maxPostsPerSlice": 0,
  "maxItems": 0,
  "resumeStoreName": "facebook-posts-backfill",
  "includePostDetails": false,
  "compact": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

The dataset of Facebook posts found (one item per post).

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

Per-search counts (read, filtered, delivered, pages), requests made and bytes transferred.

## `coverage` (type: `string`):

One line per keyword and date window: finished or not, why it stopped, pages and posts in this run and over all runs.

# 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 = {
    "searchQueries": [
        "coffee"
    ],
    "startDate": "2 months",
    "maxPagesPerSlice": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("topapi/facebook-posts-backfill-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 = {
    "searchQueries": ["coffee"],
    "startDate": "2 months",
    "maxPagesPerSlice": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("topapi/facebook-posts-backfill-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 '{
  "searchQueries": [
    "coffee"
  ],
  "startDate": "2 months",
  "maxPagesPerSlice": 2
}' |
apify call topapi/facebook-posts-backfill-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,topapi/facebook-posts-backfill-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/szGEJF0KONYThJ1xS/builds/cx5APY8RW1Ha1HJT6/openapi.json
