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

Just provide the hashtag. Post ID, user details, reactions (Like, Love, Care, Wow, Haha, Angry, Sad), comments, shares, views, timestamp — all data will be collected and stored directly in your Apify dataset.

Works with residential proxies for stable and reliable scraping.

- **URL**: https://apify.com/datapilot/facebook-hashtag-search-scraper.md
- **Developed by:** [Data Pilot](https://apify.com/datapilot) (community)
- **Categories:** Travel, Other
- **Features:** Limited permissions
- **Stats:** 45 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 scraped post 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/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 Hashtag Search Scraper

🚀 **Facebook Hashtag Search Scraper** is a powerful Apify Actor designed to extract public posts by hashtag from **Facebook** without using the official Facebook API. It leverages **residential proxies** to avoid IP blocks and delivers rich, structured data – perfect for **hashtag analytics**, trend monitoring, influencer discovery, and social media research.

### 🔥 Features

- **No Official API Required** – scrapes public **Facebook hashtag** content directly, serving as a true **Facebook API alternative**.
- **Smart Proxy Integration** – uses **Apify residential proxies** to avoid IP blocks and achieve **Facebook rate limit bypass**, ensuring reliable **Facebook data extraction**.
- **Hashtag‑Centric Search** – enter any hashtag (with or without `#`) and get sample posts that include it.
- **Rich Post Metadata** – extracts **post ID**, **user details** (name, ID, URL, avatar), **post URL**, **text**, **top reactions** (Like, Love, Care, Wow, Haha, Angry, Sad), **comments count**, **shares count**, **video view count**, **timestamp**, and **attachments** (video type, duration, ID).
- **Structured Output** – nested JSON objects make it easy to integrate with analytics pipelines.
- **Apify Dataset Ready** – each post is pushed as a separate dataset item for easy export (JSON, CSV, XML).
- **Async Architecture** – fast, non‑blocking **async Python scraper** built with asyncio.
- **Lightweight & Extensible** – sample data generation can be replaced with real scraping logic using tools like `facebook-scraper`, `Playwright`, or `Selenium`.

***

### ⚙️ How It Works

1. **Input** – Provide a **hashtag** (e.g., `"travel"` or `"#travel"`). The Actor accepts `hashtag`, `hashtags`, or `query` keys.
2. **Proxy** – Actor initialises a **residential proxy** via Apify Proxy (recommended for **Facebook anti-block**).
3. **Scrape** – For the given hashtag, the Actor generates sample posts (or you can replace the logic with real scraping). The current implementation demonstrates the data structure and proxy integration.
4. **Output** – Each post's data is pushed to the Apify Dataset – a perfect **Facebook hashtag data export** solution.
5. **Finish** – Logs total scraped posts and exits.

***

### 📥 Input

The Actor accepts a JSON input with the following fields:

| Field                 | Type   | Default  | Description |
|-----------------------|--------|----------|-------------|
| `hashtag`             | string | required | The hashtag to search for (e.g., `"travel"` or `"#travel"`). The Actor also accepts `hashtags` or `query` for backward compatibility. |
| `proxyConfiguration`  | object | `{"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"]}` | Proxy settings – **Facebook residential proxy** recommended. |

**Example input:**

```json
{
  "hashtag": "travel",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

***

### 📤 Output

Each dataset item corresponds to one Facebook post containing the hashtag:

| Field              | Type    | Description |
|--------------------|---------|-------------|
| `postId`           | string  | Unique identifier of the post. |
| `user`             | object  | Nested object containing: name (display name), id (user ID), url (profile URL), avatar (profile picture URL). |
| `url`              | string  | Direct URL to the post. |
| `text`             | string  | The post's text content. |
| `topReactions`     | object  | Nested object with reaction counts: Like, Love, Care, Wow, Haha, Angry, Sad. |
| `commentsCount`    | int     | Number of comments on the post – Facebook comment count. |
| `sharesCount`      | int     | Number of shares – Facebook share count. |
| `videoViewCount`   | int     | Number of video views (if post contains a video). |
| `time`             | string  | Human‑readable timestamp (e.g., "2025-02-14 12:34:56"). |
| `timestamp`        | int     | Unix timestamp of the post. |
| `attachments`      | array   | List of attachment objects. Currently includes type (e.g., "Video"), id, and duration. |
| `hashtag`          | string  | The original hashtag used for the search. |

**Example output item:**

```json
{
  "postId": "123456789012345678",
  "user": {
    "name": "Creator_456",
    "id": "987654321098765",
    "url": "https://www.facebook.com/profile.php?id=1",
    "avatar": "https://scontent.xx.fbcdn.net/v/profile_pic.jpg"
  },
  "url": "https://www.facebook.com/reel/123456789012345/",
  "text": "Amazing content for #travel! This is exactly what you were looking for.",
  "topReactions": {
    "Like": 45678,
    "Love": 12345,
    "Care": 789,
    "Wow": 234,
    "Haha": 56,
    "Angry": 3,
    "Sad": 1
  },
  "commentsCount": 2345,
  "sharesCount": 1234,
  "videoViewCount": 1234567,
  "time": "2025-02-14 12:34:56",
  "timestamp": 1739532896,
  "attachments": [
    {
      "type": "Video",
      "id": "987654321012345",
      "duration": 45.67
    }
  ],
  "hashtag": "travel"
}
```

***

### 🧰 Technical Stack

- **Core Scraper:** `facebook-scraper`, `Playwright`, or `Selenium` – flexible integration for Facebook hashtag extraction.
- **Proxy:** Apify Proxy with RESIDENTIAL group – real peer IPs, high anonymity.
- **Platform:** Apify Actor – serverless, scalable, integrated with Dataset and Key‑Value Store.
- **Deployment:** One‑click run on Apify Console or via REST API.

***

### 🎯 Use Cases

- **Hashtag Analytics** – track hashtag performance and engagement metrics on Facebook.
- **Trend Monitoring** – identify trending hashtags and viral content in real-time.
- **Influencer Discovery** – find influencers using specific hashtags in your niche.
- **Competitor Research** – analyse hashtags used by competitors and their engagement.
- **Content Strategy** – understand which hashtags drive engagement and reach on Facebook.
- **Brand Monitoring** – track brand hashtags and user-generated content (#UGC).
- **Market Research** – gather insights on consumer preferences through hashtag analysis.
- **Social Listening** – monitor conversations around specific topics and campaigns.
- **Campaign Analysis** – measure the success of hashtag campaigns and promotions.
- **Academic Research** – collect Facebook data for social media and marketing studies.
- **Influencer Marketing** – identify and track influencer content with specific hashtags.
- **Crisis Management** – monitor hashtags during brand emergencies or controversies.

***

### 🚀 Quick Start

1. **Open in Apify Console** – visit the Actor page and click Try for free.
2. **Paste or type a hashtag** in the input field (e.g., `"travel"` or `"#travel"`).
3. **Enable residential proxies** (recommended for reliable access).
4. **Click Start** and wait for results.
5. **Export** – download post metadata as JSON, CSV, HTML, or Excel.

You can also call this Actor programmatically via Apify SDK or REST API – ideal for automated pipelines and scheduled hashtag monitoring.

***

### 💎 Why Use This Actor?

| Feature | Benefit |
|---------|---------|
| ✅ No Facebook API quotas | Extract unlimited hashtag posts without API rate limits. |
| ✅ Residential proxies | Bypass Facebook anti-bot detection – high success rate. |
| ✅ Rich metadata | Get detailed post stats, reactions, user info, and attachments. |
| ✅ Structured output | Nested JSON objects ready for analytics and database ingestion. |
| ✅ Clean schema | Ready for immediate analysis or integration with other tools. |
| ✅ Apify ecosystem | Seamless integration with other Actors, triggers, and webhooks. |
| ✅ No authentication | Works with public Facebook hashtag content – no login required. |
| ✅ Extensible | Easily customise to add more fields or integrate advanced tools. |

***

### ⚠️ Important Notes

- **Facebook Terms of Service** – Use responsibly and at reasonable speed. This Actor is meant for personal, educational, or research use on public data only.
- **Proxy Credits** – Residential proxy usage consumes Apify platform credits. Free tier may have limited availability.
- **Rate Limiting** – Facebook aggressively rate limits scrapers. Use reasonable intervals between requests and consider distributed scraping.
- **Public Data Only** – Only scrape publicly available posts and hashtags. Respect user privacy and Facebook's policies.
- **Dynamic Content** – Facebook heavily relies on JavaScript rendering. For best results, consider integrating with Playwright or Puppeteer for JavaScript-rendered content.
- **Hashtag Format** – Enter hashtags with or without the `#` symbol – the Actor handles both formats.
- **Library Updates** – If Facebook changes its structure, the underlying scraping library may need updates. We monitor and maintain regularly.

### 📦 Changelog

#### v1.0.0 (February 2025)

- Initial release with residential proxy support.
- Hashtag-centric search functionality.
- Extracts comprehensive post metadata including reactions and user details.
- Rich nested JSON structure for easy integration.
- Sample data generation for demo purposes.
- Easily extensible for real scraping integration.
- Full Apify Actor integration.

***

### 🧑‍💻 Support & Feedback

- **Issues & Ideas:** Open a ticket on the Apify Actor issue tracker.
- **Contributions:** Pull requests are welcome via the GitHub repository.
- **Documentation:** Visit Apify Docs for platform guides.
- **Community:** Join the Apify community forum for discussions and support.

***

# Actor input Schema

## `hashtags` (type: `string`):

Enter hashtags (one per line, with or without #)

## `useResidentialProxy` (type: `boolean`):

Enable Apify Residential Proxy (default: enabled)

## `proxyCountry` (type: `string`):

Select country for proxy routing

## `upload_to_dataset` (type: `boolean`):

Save results to Apify dataset

## Actor input object example

```json
{
  "hashtags": "travel\nadventure\nlifestyle",
  "useResidentialProxy": true,
  "proxyCountry": "US",
  "upload_to_dataset": 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 = {
    "hashtags": `travel
adventure
lifestyle`
};

// Run the Actor and wait for it to finish
const run = await client.actor("datapilot/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 = { "hashtags": """travel
adventure
lifestyle""" }

# Run the Actor and wait for it to finish
run = client.actor("datapilot/facebook-hashtag-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 '{
  "hashtags": "travel\\nadventure\\nlifestyle"
}' |
apify call datapilot/facebook-hashtag-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datapilot/facebook-hashtag-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/UTItUEvcFy0YImEnT/builds/tjGEnne77kd1Ywp3e/openapi.json