# Facebook API (ScrapeIO)

12 endpoints for public Facebook data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/facebook/profile

Facebook profile or Page: name, avatar, followers, category. Price: 5 credits. MCP tool: `facebook_profile`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook profile or Page URL, profile.php?id= URL, numeric id, or Page name. |

```bash
curl "https://scrapeio.com/v1/facebook/profile?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/profile/posts

Posts from a profile or Page with reactions, comments and shares. Price: 5 credits. MCP tool: `facebook_profile_posts`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook profile or Page URL, profile.php?id= URL, numeric id, or Page name. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/facebook/profile/posts?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/profile/reels

Videos and reels from a profile or Page with view counts. Price: 5 credits. MCP tool: `facebook_profile_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook profile or Page URL, profile.php?id= URL, numeric id, or Page name. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/facebook/profile/reels?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/post

One Facebook post, video or reel by URL: views, reactions, comments, shares, video URL. Price: 5 credits. MCP tool: `facebook_post`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook post, video or reel URL. |

```bash
curl "https://scrapeio.com/v1/facebook/post?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/post/comments

Top-level comments on a Facebook post or video. Price: 5 credits. MCP tool: `facebook_comments`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook post or video URL. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/facebook/post/comments?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/group

Facebook Group Info Price: 5 credits. MCP tool: `facebook_group`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | The Facebook group URL. |
| `group_id` | string | no | The numeric Facebook group ID. |

```bash
curl "https://scrapeio.com/v1/facebook/group" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/group/posts

Facebook Group Posts Price: 5 credits. MCP tool: `facebook_group_posts`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | The URL of the group |
| `group_id` | string | no | The ID of the group |
| `sort_by` | string (TOP_POSTS, RECENT_ACTIVITY, CHRONOLOGICAL, CHRONOLOGICAL_LISTINGS) | no | How to sort the posts. |
| `cursor` | string | no | The cursor to paginate to the next page |

```bash
curl "https://scrapeio.com/v1/facebook/group/posts" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/post/comment/replies

Comment Replies Price: 5 credits. MCP tool: `facebook_post_comment_replies`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `feedback_id` | string | yes | The feedbackid of the comment. |
| `expansion_token` | string | yes | The expansiontoken of the comment. |
| `cursor` | string | no | The cursor to paginate to the next page |

```bash
curl "https://scrapeio.com/v1/facebook/post/comment/replies?feedback_id=...&expansion_token=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/post/transcript

Transcript Price: 5 credits. MCP tool: `facebook_post_transcript`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook post URL |
| `cache_max_age` | string (1d, 3d, 7d, 14d, 30d) | no | If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "ca |

```bash
curl "https://scrapeio.com/v1/facebook/post/transcript?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/profile/events

Profile Events Price: 5 credits. MCP tool: `facebook_profile_events`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The URL of the public Facebook page |
| `cursor` | string | no | The cursor to paginate to get more events |

```bash
curl "https://scrapeio.com/v1/facebook/profile/events?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/profile/photos

Profile Photos Price: 5 credits. MCP tool: `facebook_profile_photos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Facebook page URL |
| `next_page_id` | string | no | To paginate through to the next page |
| `cursor` | string | no | To paginate through to the next page |

```bash
curl "https://scrapeio.com/v1/facebook/profile/photos?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/search/videos

Search Videos Price: 5 credits. MCP tool: `facebook_search_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | The keyword or phrase to search for |
| `cursor` | string | no | The opaque cursor returned by the previous response. |

```bash
curl "https://scrapeio.com/v1/facebook/search/videos?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```