# 🔍 Facebook Hashtag Search Scraper (`scrapium/facebook-hashtag-search-scraper`) Actor

Scrape Facebook hashtag search results — posts, reels, reactions, comments, shares, attachments and full Reels metadata. Built for speed and scale.

- **URL**: https://apify.com/scrapium/facebook-hashtag-search-scraper.md
- **Developed by:** [Scrapium](https://apify.com/scrapium) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## 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 Hashtag Search Scraper

**Scrape Facebook hashtag search results at scale — posts, reels, reactions, comments, shares, attachments and full Reels metadata.** Bulk hashtag input, automatic proxy fallback, and live streaming output. Built for marketers, growth teams, researchers and trend hunters.

***

### 🌟 Why Choose Us?

- ⚡ **Blazing fast** — async-first scraper with batched per-video enrichment.
- 🧱 **Production grade** — proxy fallback chain (`none → datacenter → residential`) keeps you collecting even when Facebook tightens up.
- 📡 **Live output** — every post lands in your dataset the moment it's scraped; a mid-run failure never costs you the data you already paid for.
- 🎬 **Rich Reels metadata** — Video posts are auto-enriched with full FB Shorts metadata (DRM info, muted segments, thumbnails, soundtracks, owners and more).
- 🏷️ **Bulk hashtags** — run dozens of hashtags in a single execution.
- 🎨 **Beautiful dataset view** — output table renders with labeled columns and emoji headers in the Apify Console.

***

### 🎯 Key Features

- 🔎 Hashtag and hashtag-URL input (mix and match)
- 📦 Per-hashtag max-post limit
- 🍪 Cookie-based authentication
- 🌐 Automatic proxy escalation if Facebook starts blocking
- 🎞️ Full Reels / FB Shorts metadata for video attachments
- ❤️ Reactions, comments, shares, views per post
- 🕒 Post timestamps and authors with avatars
- 💾 Live dataset streaming — every post pushed as soon as it's extracted

***

### 📥 Input

```json
{
  "searchQueries": ["football", "travel"],
  "maxItems": 50,
  "c_user": "YOUR_C_USER",
  "xs": "YOUR_XS_TOKEN",
  "proxyConfiguration": { "useApifyProxy": false }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `searchQueries` | `string[]` | 🏷️ One or more hashtags (`football`) or hashtag URLs (`https://www.facebook.com/hashtag/football`). |
| `maxItems` | `integer` | 📦 Max posts to collect **per hashtag**. Default `50`. |
| `c_user` | `string` | 🍪 Your Facebook `c_user` cookie (numeric user ID). **Required.** |
| `xs` | `string` | 🍪 Your Facebook `xs` cookie (URL-encoded session token). **Required.** |
| `proxyConfiguration` | `object` | 🌐 Apify proxy config. Default = no proxy. The actor automatically falls back to **datacenter → residential** if Facebook starts blocking. |

***

### 📤 Output

Each pushed dataset record:

```json
{
  "searchQuery": "football",
  "postId": "1017535753998725",
  "user": {
    "name": "খেলাযোগ",
    "id": "100072269304011",
    "url": "https://www.facebook.com/profile.php?id=100072269304011",
    "avatar": "https://scontent.../profile.jpg"
  },
  "url": "https://www.facebook.com/1017535753998725",
  "text": "আর নয় অপেক্ষা…",
  "topReactions": { "Like": 269, "Love": 89, "Care": 14, "Haha": 3 },
  "commentsCount": 15,
  "sharesCount": 0,
  "videoViewCount": 1435,
  "time": "2026-05-14 13:30:39",
  "timestamp": 1778743839,
  "attachments": [
    {
      "deduplication_key": "",
      "target": { "__typename": "Video", "id": "2193122174769647" },
      "__typename": "StoryAttachment",
      "style_list": ["fb_shorts_creation", "video", "fallback"],
      "styles": { /* full Reels metadata */ },
      "media": { /* video media blob */ },
      "all_subattachments": { "nodes": [] }
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `searchQuery` | 🏷️ The hashtag that produced this post. |
| `postId` | 🆔 Facebook post ID. |
| `user` | 👤 Post author (name, id, profile url, avatar). |
| `url` | 🔗 Canonical post URL. |
| `text` | 📝 Post caption / message. |
| `topReactions` | ❤️ Reaction counts keyed by reaction name. |
| `commentsCount` / `sharesCount` | 💬🔁 Engagement counts. |
| `videoViewCount` | 👁️ Total video views (videos / Reels only). |
| `time` / `timestamp` | 🕒⏰ Post creation time (formatted + unix). |
| `attachments` | 📎 Full attachments array, including rich Reels metadata for videos. |

***

### 🚀 How to Use (Apify Console)

1. 🔐 Log in at **[console.apify.com](https://console.apify.com)** → **Actors**.
2. 🔎 Find **Facebook Hashtag Search Scraper** in your actor list and open it.
3. 🍪 Paste your Facebook cookies (use Cookie-Editor or EditThisCookie to export — at minimum `c_user` and `xs`).
4. 🏷️ Enter one or more hashtags or hashtag URLs.
5. 🌐 Leave proxy on **default (no proxy)** unless you specifically need one — the actor escalates automatically if needed.
6. ▶️ Click **Start**.
7. 📊 Watch logs stream live with engagement stats per scraped post.
8. 💾 Open the **Output** tab and export to JSON / CSV / XLSX.

***

### 🤖 Use via API / MCP

**Start a run:**

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/runs?token=$APIFY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "searchQueries": ["football"],
       "maxItems": 50,
       "cookies": [
         { "name": "c_user", "value": "..." },
         { "name": "xs", "value": "..." }
       ]
     }'
```

**Run and wait (sync) — get the dataset back immediately:**

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"searchQueries":["travel"], "maxItems":20, "cookies":[...]}'
```

***

### 💡 Best Use Cases

- 📈 **Trend & topic research** — capture what people post under any hashtag right now.
- 🎯 **Audience analysis** — pull reaction / comment patterns for content benchmarking.
- 🧠 **Content ideation** — see what top-performing posts in your niche look like.
- 📰 **Real-time monitoring** — track breaking-topic hashtags and surface viral posts.
- 🎬 **Creator research** — pull full Reels metadata for short-form video studies.

***

### 💰 Pricing

This actor uses **pay-per-event** billing. You pay for:

| Event | Description |
|-------|-------------|
| **Actor start** | One-time platform start charge. |
| **Scraped post** | One charge per post written to the output dataset. |

Runs stop **cleanly** when your charge limit is reached — you keep everything scraped up to that point.

***

### ❓ Frequently Asked Questions

**Where do I get the cookies?**
Use a Chrome / Firefox cookie-export extension (Cookie-Editor, EditThisCookie). Open `facebook.com` while logged in, export cookies for the facebook.com domain, and paste them into the `cookies` input. Only `c_user` and `xs` are strictly required.

**Why do I need cookies at all?**
Facebook's hashtag search results are only returned to authenticated sessions. Without valid cookies the search endpoint returns no usable data.

**My run shows "switching to datacenter proxy" / "switching to residential proxy".**
That's the automatic fallback chain at work — Facebook blocked the direct request and the actor escalated. Output continues normally. You can also start at residential directly via the proxy input.

**Can I run multiple hashtags in one run?**
Yes — provide them all in `searchQueries`. Each hashtag is processed sequentially, with a clear log section per hashtag and live output to the same dataset.

**Will my data survive a crash?**
Yes. Every post is pushed to the dataset *the moment it's scraped*. A mid-run failure leaves a partial dataset, never an empty one.

***

### 🛟 Support & Feedback

🐞 Found a bug? Have a feature request? Open an issue on the actor's Apify page — we read every report.

***

### ⚖️ Legal & Compliance

- 📂 Only public hashtag-search results are collected.
- 🔒 Never scrape behind authentication you haven't been authorized to use.
- 🌐 You are responsible for complying with Facebook's Terms of Service, GDPR / CCPA, and any local data-protection laws applicable to your use case.

# Actor input Schema

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

🔎 Enter one or more **hashtags** (e.g. `football`, `travel`) or full Facebook hashtag URLs (e.g. `https://www.facebook.com/hashtag/football`). Both formats are accepted and bulk input is fully supported.

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

🎯 Maximum number of posts to scrape **per hashtag**. Higher = more data, longer runtime.

## `c_user` (type: `string`):

Your Facebook session cookie `c_user` (the numeric user ID). Copy it from your browser DevTools → Application → Cookies → www.facebook.com. Required to authenticate the scraper against Facebook's GraphQL API. 🔑

## `xs` (type: `string`):

Your Facebook session cookie `xs` (URL-encoded session token). Copy it from your browser DevTools → Application → Cookies → www.facebook.com. Keep it secret — it grants access to your account. 🔐

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

🛡️ By default the actor runs **without a proxy**. If Facebook rejects or rate-limits the request, the actor automatically falls back to a **datacenter proxy**, then to a **residential proxy** (with up to 3 retries). Once a fallback is engaged, the residential proxy stays in use for the rest of the run.

## Actor input object example

```json
{
  "searchQueries": [
    "football"
  ],
  "maxItems": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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": [
        "football"
    ],
    "c_user": "",
    "xs": "",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapium/facebook-hashtag-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 = {
    "searchQueries": ["football"],
    "c_user": "",
    "xs": "",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapium/facebook-hashtag-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 '{
  "searchQueries": [
    "football"
  ],
  "c_user": "",
  "xs": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapium/facebook-hashtag-search-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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