> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Facebook Posts and Groups API

> Posts and reels from any public Facebook page, profile or group: text, author, reactions by type, comments, shares, views, media, links and mentions.

`POST /v1/data/facebook/posts/run`

**Pricing:** $0.005 per post ($5.00 per 1,000).

Pull recent posts and reels from a public Facebook page/profile URL, or member posts from a public group URL.

## Ways to call it

* **Page or Profile**: set `urls` (optional: `maxResults`, `onlyPostsNewerThan`, `onlyPostsOlderThan`)
* **Group**: set `groupUrls` (optional: `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**urls** `string`

Public Facebook page or profile URL to scrape posts from (e.g. facebook.com/nike or facebook.com/zuck). Private profiles return no results. Use this OR Group URL, not both.

Format e.g. `https://www.facebook.com/nike`.

**groupUrls** `string`

Public Facebook group URL to scrape member posts from (e.g. facebook.com/groups/\<group>). Use this OR Page or Profile URL, not both.

Format e.g. `https://www.facebook.com/groups/1082450387678660`.

**maxResults** `integer`

Number of posts to return. Use 0 for all.

**onlyPostsNewerThan** `date`

Only get posts published on or after this date (YYYY-MM-DD).

**onlyPostsOlderThan** `date`

Only get posts published on or before this date (YYYY-MM-DD).

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/facebook/posts/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "urls": "https://www.facebook.com/nike",
    "maxResults": 12
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/facebook/posts/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "urls": "https://www.facebook.com/nike",
    "maxResults": 12
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/facebook/posts/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "urls": "https://www.facebook.com/nike",
  "maxResults": 12
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one post, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `contentType` | Content Type | text |
| `postUrl` | Post URL | url |
| `postId` | Post ID | text |
| `postedAt` | Posted At | datetime |
| `text` | Text | text |
| `reactions` | Reactions | number |
| `comments` | Comments | number |
| `shares` | Shares | number |
| `views` | Views | number |
| `videoDuration` | Video Duration | number |
| `reactionBreakdown` | Reaction Breakdown | object |
| `author` | Author | object |
| `source` | Source | object |
| `media` | Media | object |
| `linkPreview` | Link Preview | object |
| `mentions` | Mentions | object\_array |
| `collaborators` | Collaborators | object\_array |
| `topComments` | Top Comments | object\_array |
| `hashtags` | Hashtags | array |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "facebook/posts",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "author": {
        "name": "Nike",
        "url": "https://www.facebook.com/100044541544829",
        "id": "100044541544829",
        "avatar": "https://scontent-sjc6-1.xx.fbcdn.net/v/t39.30808-1/284964043_10159903868513445_7696353984967674128_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx400x400&ctp=s50x50&_nc_ca..."
      },
      "reactionBreakdown": {
        "like": 6191,
        "love": 1127,
        "wow": 40,
        "haha": 22,
        "sad": 5,
        "angry": 31,
        "care": 132
      },
      "collaborators": [],
      "source": {
        "name": "nike",
        "url": "https://www.facebook.com/nike"
      },
      "postedAt": "2025-09-15T16:01:59.000Z",
      "videoDuration": 30025,
      "topComments": [
        {
          "author": "Kaya Coruk",
          "url": "https://www.facebook.com/kaya.coruh",
          "text": "When will you make special shoes for Alperen Sengun? How about the name Air Alpi?  😃",
          "likes": 38,
          "date": "2025-10-24T18:45:54.000Z"
        }
      ],
      "contentType": "VIDEO",
      "media": {
        "type": "Video",
        "url": "https://scontent-sjc6-1.xx.fbcdn.net/v/t51.82787-10/549104239_18565912819020081_2330706867671026439_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p296x100&_nc_c...",
        "videoUrl": "https://video-sjc3-1.xx.fbcdn.net/o1/v/t2/f2/m86/AQNrPdap6OftBP5OG6byX9Zra9AIeTlJgFFSnCnQtKX-YrtZwceyclf7S_s9vyochvQvd5rnHPfbDksk867PaxJsnJKbOjIMokT-UHM.mp4?...",
        "thumbnailUrl": "https://scontent-sjc6-1.xx.fbcdn.net/v/t51.82787-10/549104239_18565912819020081_2330706867671026439_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=s960x960&_nc_c...",
        "imageOcr": null
      },
      "shares": 1098,
      "postUrl": "https://www.facebook.com/100044541544829/posts/1393461115481927",
      "text": "Leave your limits at the surface. #JustDoIt",
      "linkPreview": null,
      "views": 3221498,
      "comments": 2288,
      "reactions": 7548,
      "mentions": [],
      "postId": "1393461115481927",
      "hashtags": [
        "#justdoit"
      ]
    }
  ]
}
```

## Related APIs

To search posts by keyword instead of by page use [`facebook/posts-search`](https://docs.mindcase.co/apis/facebook/posts-search); for comments on a post use [`facebook/comments`](https://docs.mindcase.co/apis/facebook/comments); for reels with play counts use [`facebook/reels`](https://docs.mindcase.co/apis/facebook/reels).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.