# FB Friends Count (`ratulislam/fb-friends-count`) Actor

Checks Facebook friend counts for up to 25 cookie + c_user sessions per run. Returns one contract-shaped dataset item per account.

- **URL**: https://apify.com/ratulislam/fb-friends-count.md
- **Developed by:** [Ratul Islam](https://apify.com/ratulislam) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 FB Friends Count do?

**FB Friends Count** reads the **friend count** of up to 25 Facebook profiles per run, using your own logged-in Facebook sessions. Give it `{cookie, cUser}` pairs and it returns one result item per account — either the count or a machine-readable error. It is a lightweight API-style Actor (plain HTTPS + regex, no browser), ported from a proven `readFriendCount` helper, so runs finish in seconds. It only touches [facebook.com](https://www.facebook.com) profile pages you already have session cookies for.

### Why use FB Friends Count?

- **Session health + count in one call:** a returned count proves the cookie is alive; an `invalid_cookie` or `session_challenge` error tells you exactly which session needs replacing.
- **Batch-ready:** check up to 25 sessions in one run with per-account items, so one expired cookie never sinks the whole batch.
- **Stable contract:** every item has identical keys; branch on `error.code`, never on message text.
- **Platform advantages:** schedule nightly session-health checks, call it from the Apify API, rotate through Apify Proxy automatically, and monitor runs in Console.

#### Main features

- Cookie → friend count via the `friends_all` profile view
- Contract envelope on every item (success and failure share one shape)
- Flat error catalog: `invalid_input`, `invalid_cookie`, `session_challenge`, `rate_limited`, `upstream_error`, `service_unavailable`
- Run summary (`OUTPUT`) with totals and errors grouped by code

### What data can FB Friends Count extract?

| Field | Type | Description |
|---|---|---|
| `friendCount` | integer | Number of friends, or `0` for a valid page with no count |
| `ok` | boolean | `true` when the check ran (even for 0 friends) |
| `input` | string | Echo of the `cUser` that was checked |
| `error` | object | `{code, message, retryable}` — `null` on success |
| `checkedAt` | string | ISO timestamp of the check |
| `runId` | string | Apify run id (or `local-run` locally) |

Unused contract fields (`eligible`, `pageName`, `linkedNumber`, `banReason`) are always `null` for this Actor.

### How to check Facebook friend counts

1. Log in to Facebook in your browser and copy the raw cookie header plus the `c_user` value of each session you want to check.
2. Open the Actor, paste up to 25 `{cookie, cUser}` pairs into the **accounts** input, and leave **Proxy configuration** on Apify Proxy.
3. Click **Start** and wait for status SUCCEEDED (usually under a minute).
4. Open the **Dataset** tab: each item holds one account's `friendCount` or its error.
5. Replace any cookie whose item reports `invalid_cookie` or `session_challenge`, then re-run.

### How much will it cost to check friend counts?

Each account is one tiny HTTPS request, so compute usage is minimal — far below one compute unit per run at 25 accounts. Apify Proxy traffic is likewise a few kilobytes per account. The free tier covers thousands of such checks per month; larger plans just raise the scheduling and retention limits.

### Input

See the input tab for full configuration options. `accounts` is a JSON array (1–25 items) of `{"cookie": "<raw cookie header>", "cUser": "<numeric id>"}`. The cookie must belong to the `cUser` it is paired with. `proxyConfiguration` uses the standard proxy editor and defaults to Apify Proxy, which Facebook-facing runs need.

```json
{
  "accounts": [{ "cookie": "c_user=61592912563278; xs=...; fr=...", "cUser": "61592912563278" }],
  "proxyConfiguration": { "useApifyProxy": true }
}
```

### Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. A success item and an error item look like this:

```json
{
  "ok": true,
  "actor": "fb-friends-count",
  "input": "61592912563278",
  "eligible": null,
  "pageName": null,
  "linkedNumber": null,
  "banReason": null,
  "friendCount": 132,
  "error": null,
  "checkedAt": "2026-10-13T12:00:00.000Z",
  "runId": "abc123XYZ"
}
```

```json
{
  "ok": false,
  "actor": "fb-friends-count",
  "input": "61592912563278",
  "eligible": null,
  "pageName": null,
  "linkedNumber": null,
  "banReason": null,
  "friendCount": null,
  "error": { "code": "invalid_cookie", "message": "Cookie was rejected by Facebook (HTTP 400). Get a fresh logged-in cookie and retry.", "retryable": false },
  "checkedAt": "2026-10-13T12:00:00.000Z",
  "runId": "abc123XYZ"
}
```

The `OUTPUT` record in the key-value store summarizes the run:

```json
{ "actor": "fb-friends-count", "runId": "abc123XYZ", "total": 2, "succeeded": 1, "failed": 1, "errorsByCode": { "invalid_cookie": 1 } }
```

### Tips

- **Keep batches at 25 or fewer.** Larger lists are rejected with `invalid_input` — split them across runs instead.
- **Pair cookies correctly.** A cookie checked against someone else's `cUser` reads the wrong profile; always echo-check `input` in the output.
- **Back off on `rate_limited`.** That error is retryable; wait a few minutes before re-running those accounts.
- **Refresh proactively.** Schedule a daily run over your session pool and rotate cookies as soon as `invalid_cookie` appears, before downstream automations feel it.

### FAQ, disclaimers, and support

#### Is this an official Facebook API?

No. It reads the same profile page a logged-in browser sees, using sessions you supply. Respect Facebook's Terms of Service and your local laws.

#### Why did I get `session_challenge`?

Facebook showed a login/2FA challenge for that session. Log in as that account in a real browser, complete the challenge, export a fresh cookie, and retry.

#### Why is `friendCount` 0 — is that an error?

No. `ok: true` with `0` means the page loaded fine but exposed no count (for example a brand-new profile). Only `ok: false` items are failures.

> Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

Found a bug or need a feature? Use the Issues tab. For programmatic access (scheduling, API calls, integrations), see the API tab.

# Actor input Schema

## `accounts` (type: `array`):

Cookie + c_user pairs to check: a non-empty array, at most 25 items per run. Each item needs the raw Facebook cookie header and the numeric profile id (c_user) that cookie belongs to. The Actor validates this and reports invalid_input items for bad entries.

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

Proxy settings. Facebook blocks bare datacenter IPs, so keep Apify Proxy enabled for platform runs.

## Actor input object example

```json
{
  "accounts": [
    {
      "cookie": "c_user=61592912563278; xs=...",
      "cUser": "61592912563278"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset with one item per checked account (ok plus friendCount, or ok false plus a contract error).

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

Totals, succeeded/failed counts, and error counts by code from the OUTPUT record.

# 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("ratulislam/fb-friends-count").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("ratulislam/fb-friends-count").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 '{}' |
apify call ratulislam/fb-friends-count --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ratulislam/fb-friends-count"
        }
    }
}
```

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/St7X0HVPG91KvQ91i/builds/vH2YCVWzY8rPmZbrs/openapi.json