# Facebook Groups Scraper Pro (`ayeeyee/facebook-groups-scraper-pro`) Actor

Scrape Facebook group members, posts, and engagement metrics. Multi-provider fallback chain (desktop Playwright + mobile HTML). Member + post filters. MCP-ready providerHealth. No paid API keys.

- **URL**: https://apify.com/ayeeyee/facebook-groups-scraper-pro.md
- **Developed by:** [Virtual Footprint LLC](https://apify.com/ayeeyee) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.21 / 1,000 group item extracteds

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

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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 Groups Scraper Pro

![Apify](https://img.shields.io/badge/Apify-Actor-ff6b37?logo=apify)
![Version](https://img.shields.io/badge/version-1.0-blue)
![Pricing](https://img.shields.io/badge/pricing-PAY_PER_EVENT-success)
![Modes](https://img.shields.io/badge/modes-fast_lookup%7Cenrich%7Cbatch-orange)
![MCP-ready](https://img.shields.io/badge/MCP-ready-brightgreen)

> Facebook group members, posts, and engagement metrics with MCP-ready providerHealth. Multi-provider fallback. No paid API keys.

---

### Why This Actor Is Better

The Facebook Groups scraper built for marketing agencies and lead-gen teams. Extracts group metadata, member lists (names + profile URLs), and recent posts with engagement metrics (likes, comments, engagement bands). Multi-provider fallback (Playwright desktop + mobile HTML), keyword post filtering, and MCP-ready providerHealth metadata.

#### Key Features

- Member extraction — names and profile URLs from the group members tab
- Post extraction — recent posts with author, text, likes, and comments
- Engagement bands — automatic viral/high/medium/low/minimal classification
- Multi-provider fallback — Playwright desktop primary, mobile HTML fallback
- Keyword filtering — slice posts by body keyword
- Member count normalization — '1.2K members' → 1200
- Confidence scoring — every group gets a 0.0-1.0 score weighted by completeness
- Source attribution + providerHealth — MCP agents can route around blocks
- Cache-first mode — fast_lookup hits the Apify KVS cache for sub-second repeats
- Transparent PPE pricing — $2.21/1K results, $0.50/1K members, $1/1K posts

---

### Architecture

````

Input (queries + mode)
|
v
\[Cache check] --hit--> return base data (<800ms)
|miss
v
\[Primary provider: scrape\_groups\_desktop]
|-- on failure --> \[Fallback provider]
v
\[Normalization + field mapping]
|
v
\[Enrichment layer]
|
v
\[Confidence scoring + source attribution + providerHealth]
|
v
\[Progressive dataset push] (one push per result)
|
v
\[Webhook + MCP-ready metadata]

````

Every result includes `providerHealth{}` tracking per-provider status, latency, and errors — making this actor safe to call from MCP agents that need to route around failures.

---

### Modes

| Mode | Description | Target latency | Use case |
|---|---|---|---|
| `fast_lookup` | Cache-first, base data only | <800ms cached | Quick lookups, deduplication |
| `enrich` | Full enrichment with contact extraction + scoring | ~2-4s/result | Detailed analysis |
| `batch` | Queue-based, full enrichment, per-item isolation | varies | Large query lists (100+) |

---

### Input

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `mode` | string | — | `enrich` | `fast_lookup` \| `enrich` \| `batch` |
| `queries` | array | yes | `["https://www.facebook.com/groups/digitalmarketing"]` | Search queries |
| `maxResults` | integer | — | `25` | Max results per query (1-1000) |
| `webhookUrl` | string | — | — | Webhook for completion notification |

#### Example input

```json
{
  "mode": "enrich",
  "queries": ["https://www.facebook.com/groups/digitalmarketing"],
  "maxResults": 50
}
````

***

### Output

Results are stored in the Apify dataset as structured JSON. See `.actor/output_schema.json` for the canonical schema.

Every result includes:

| Field | Type | Description |
|---|---|---|
| `confidenceScore` | number | 0.0-1.0 reliability score |
| `sources` | array | Provider attribution |
| `providerHealth` | object | Per-provider status/latency/error for MCP routing |
| `cacheStatus` | string | `hit` | `miss` | `degraded` |
| `mode` | string | Execution mode used |
| `extractedAt` | string | ISO timestamp |

***

### Pricing

Transparent pay-per-event (PPE) pricing. You only pay for successful results.

| Event | Price | When charged |
|---|---|---|
| Actor Start | $0.05/1K runs | One-time per run |
| Result | $0.00221/result | Per result pushed |
| Member Extracted | $0.0005/result | Charge per group member with profile URL extracted. |
| Post Extracted | $0.001/result | Charge per group post with engagement metrics extracted. |

No monthly subscription required.

***

### Use Cases

- Lead generation — build member lists from niche-relevant groups
- Influencer research — identify high-engagement group posters
- Market research — map group size and engagement by niche
- Community monitoring — track post velocity and sentiment in target groups
- Competitor intelligence — monitor competitor groups for member growth
- Outreach — build profile-URL lists for cold messaging
- MCP agent workflows — call from LLM agents; providerHealth lets agents route

***

### Integration Examples

#### Python (Apify SDK)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("YOUR_USERNAME/facebook-groups-scraper-pro").call(run_input={
    "mode": "enrich",
    "queries": ["https://www.facebook.com/groups/digitalmarketing"],
    "maxResults": 50,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~facebook-groups-scraper-pro/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"enrich","queries":["https://www.facebook.com/groups/digitalmarketing"],"maxResults":25}'
```

#### MCP (Model Context Protocol)

This actor is MCP-ready. Register it via `@apify/actors-mcp-server`:

```bash
npx -y @apify/actors-mcp-server --tools actors,YOUR_USERNAME/facebook-groups-scraper-pro
```

Agents can then call `call-actor` and use `providerHealth` + `confidenceScore` to route around failed providers and filter result quality.

***

### FAQ

**Q: Do I need Facebook login cookies?**

No. This actor scrapes public group data via Playwright + httpx. No login or session cookies required for public groups.

**Q: What's the difference between member extraction and post extraction?**

Member extraction pulls the member list (names + profile URLs). Post extraction pulls recent posts with author, text, and engagement. Both are independent toggles — enable either or both.

**Q: How does the fallback chain work?**

Playwright desktop handles JS-rendered group pages. If blocked, mobile HTML via httpx takes over with reduced fidelity (group name + member count only). providerHealth shows which providers succeeded.

**Q: Can I filter posts by keyword?**

Yes. Use keywordFilter to only return posts whose text contains a keyword (case-insensitive).

**Q: Can I call this from an LLM agent?**

Yes. The actor is MCP-ready. Every result includes providerHealth{}, confidenceScore, and engagementBand so agents can make routing and filtering decisions.

***

### Legal & Compliance

This actor scrapes **publicly available** data. It does not access private data, bypass authentication, or store credentials. Users are responsible for complying with applicable data protection laws (GDPR, CCPA, etc.) and the target platform's Terms of Service.

This actor is intended for legitimate research, analysis, and outreach use cases. It must not be used for spam, harassment, or unlawful activity.

***

### AI-DLC / Data Lifecycle

This actor follows AI-DLC principles for ethical data handling:

- **Collection** — Public data only; respects robots.txt and rate limits.
- **Processing** — In-memory normalization; no PII logging.
- **Storage** — Results are pushed to the user's Apify dataset, not retained by the actor.
- **Usage** — Designed for analysis, enrichment, and legitimate outreach.
- **Disposal** — No long-term caching of user data between runs (cache TTL 1800s for base results only).

***

### Enhancement Roadmap (API / MCP Integrations)

- Multi-step orchestration via LangGraph conditional workflows
- Vector store integration for semantic deduplication across runs
- Additional paid enrichment APIs (user keys, disabled by default)

***

### Changelog

- v1.0 — Initial release: member + post extraction, engagement bands, Playwright+mobile fallback, MCP-ready metadata

***

### Links

- **Apify Store:** https://apify.com/YOUR\_USERNAME/facebook-groups-scraper-pro
- **Documentation:** See this README
- **Support:** Open an issue on the actor's Apify Store page

# Actor input Schema

## `mode` (type: `string`):

fast\_lookup: cache-first. enrich: full with members+posts. batch: queue-based.

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

Group URLs (e.g. https://facebook.com/groups/123) or group names

## `maxResults` (type: `integer`):

Maximum results per query (1-1000)

## `webhookUrl` (type: `string`):

Optional webhook URL for completion notification

## `extractMembers` (type: `boolean`):

Extract group member names and profile URLs.

## `extractPosts` (type: `boolean`):

Extract recent posts with engagement metrics (likes, comments).

## `maxMembers` (type: `integer`):

Hard cap on members returned per group (default 200).

## `maxPosts` (type: `integer`):

Hard cap on posts returned per group (default 50).

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

Only return posts whose text contains this keyword.

## Actor input object example

```json
{
  "mode": "enrich",
  "queries": [
    "https://www.facebook.com/groups/digitalmarketing"
  ],
  "maxResults": 25,
  "webhookUrl": "",
  "extractMembers": true,
  "extractPosts": true,
  "maxMembers": 200,
  "maxPosts": 50,
  "keywordFilter": ""
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ayeeyee/facebook-groups-scraper-pro").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ayeeyee/facebook-groups-scraper-pro").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 '{}' |
apify call ayeeyee/facebook-groups-scraper-pro --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Facebook Groups Scraper Pro",
        "description": "Scrape Facebook group members, posts, and engagement metrics. Multi-provider fallback chain (desktop Playwright + mobile HTML). Member + post filters. MCP-ready providerHealth. No paid API keys.",
        "version": "1.0",
        "x-build-id": "KixjmuP66RgdeXdnx"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/ayeeyee~facebook-groups-scraper-pro/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-ayeeyee-facebook-groups-scraper-pro",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/ayeeyee~facebook-groups-scraper-pro/runs": {
            "post": {
                "operationId": "runs-sync-ayeeyee-facebook-groups-scraper-pro",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/ayeeyee~facebook-groups-scraper-pro/run-sync": {
            "post": {
                "operationId": "run-sync-ayeeyee-facebook-groups-scraper-pro",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "queries"
                ],
                "properties": {
                    "mode": {
                        "title": "Execution Mode",
                        "enum": [
                            "fast_lookup",
                            "enrich",
                            "batch"
                        ],
                        "type": "string",
                        "description": "fast_lookup: cache-first. enrich: full with members+posts. batch: queue-based.",
                        "default": "enrich"
                    },
                    "queries": {
                        "title": "Search Queries",
                        "type": "array",
                        "description": "Group URLs (e.g. https://facebook.com/groups/123) or group names",
                        "default": [
                            "https://www.facebook.com/groups/digitalmarketing"
                        ]
                    },
                    "maxResults": {
                        "title": "Max Results per Query",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum results per query (1-1000)",
                        "default": 25
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Optional webhook URL for completion notification",
                        "default": ""
                    },
                    "extractMembers": {
                        "title": "Extract members",
                        "type": "boolean",
                        "description": "Extract group member names and profile URLs.",
                        "default": true
                    },
                    "extractPosts": {
                        "title": "Extract posts",
                        "type": "boolean",
                        "description": "Extract recent posts with engagement metrics (likes, comments).",
                        "default": true
                    },
                    "maxMembers": {
                        "title": "Max members per group",
                        "type": "integer",
                        "description": "Hard cap on members returned per group (default 200).",
                        "default": 200
                    },
                    "maxPosts": {
                        "title": "Max posts per group",
                        "type": "integer",
                        "description": "Hard cap on posts returned per group (default 50).",
                        "default": 50
                    },
                    "keywordFilter": {
                        "title": "Keyword filter (posts)",
                        "type": "string",
                        "description": "Only return posts whose text contains this keyword.",
                        "default": ""
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```