> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get](https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get.mdx](https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).

---
# List Facebook profile posts (https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get)

## Summary

Lists public posts for a Facebook profile or page identified by `url` or `pageId`, with cursor-based pagination. Private profiles, missing pages, and profiles with no public posts can all surface as HTTP `200` with an empty `data.posts` page—this route does not expose `lookupStatus`. Call `GET /v1/facebook/profiles` first when you need explicit `found` / `private` / `not_found` before interpreting an empty list.

**Tags:** `Facebook`

## HTTP

- **Method:** GET
- **Path:** `/v1/facebook/profiles/posts`
- **Base URL:** `https://api.socialfetch.dev`

## Capability summary

- **SDK mapping:** `client.facebook.getProfilePosts({ url?, pageId?, cursor? })`
- **Accepted identifiers:** `url` (query)
- **Pagination:** cursor via `cursor`, next cursor: `data.page.nextCursor`, has more: `data.page.hasMore`

## Authentication

- **`x-api-key`**: API key (`sfk_...`)

## Parameters

### `url` (query)

- **Required:** no
- **Constraints:** type `string`; minLength: 1; maxLength: 4096
- **Description:** Full public Facebook profile or page URL.

### `pageId` (query)

- **Required:** no
- **Constraints:** type `string`; minLength: 1; maxLength: 4096
- **Description:** Facebook page or profile id when you have it instead of a full URL.

### `cursor` (query)

- **Required:** no
- **Constraints:** type `string`; minLength: 1
- **Description:** Opaque pagination cursor from a previous response (`data.page.nextCursor`).

## Pagination

This endpoint uses **cursor-based pagination** via the `cursor` query parameter.

- Read **hasMore** from `data.page.hasMore`.
- When that value is `true`, read **nextCursor** from `data.page.nextCursor` and pass it as the `cursor` query parameter on the **next** request (URL-encode when building a query string).
- Omit `cursor` on the **first** request.
- Stop when **hasMore** is `false` or **nextCursor** is null (end of list).

## Responses (status codes)

- **200**: Facebook posts for the requested profile or page. Empty `data.posts` is ambiguous without a profile preflight—see the operation description.
- **400**: Invalid `url`, `pageId`, `cursor`, or bad request
- **401**: Missing or invalid API key
- **402**: Insufficient credits
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed from the response (unexpected or invalid data).
- **503**: Service temporarily unavailable; safe to retry with backoff.

## Response body (200)

Facebook posts for the requested profile or page. Empty `data.posts` is ambiguous without a profile preflight—see the operation description.

### Field outline

- **data** (required) — type `object`. Endpoint-specific response payload.
  - **posts** (required) — type `array`. Facebook posts for the requested input. An empty array can mean no public posts were returned, the profile does not expose posts publicly, or the URL or id could not be resolved—there is no separate lookup status on this route.
    - _items:_
      - **id** (required) — type `string`; minLength: 1. Facebook post id.
      - **text** (required) — type `string`; nullable. Post caption or text when present.
      - **url** (required) — type `string`; minLength: 1. Public Facebook URL for this post.
      - **publishTime** (optional) — type `integer`. When the post was published (Unix epoch seconds) when available.
      - **authorDisplayName** (optional) — type `string`; nullable. Display name for the post author when available.
      - **authorShortName** (optional) — type `string`; nullable. Short display label for the author when Facebook provides one.
      - **authorId** (optional) — type `string`. Facebook id for the post author when available.
      - **reactionCount** (optional) — type `integer`; minimum: 0. Reaction count when available.
      - **commentCount** (optional) — type `integer`; minimum: 0. Comment count when available.
      - **videoViewCount** (optional) — type `integer`; minimum: 0; nullable. Video view count when available.
      - **imageUrl** (optional) — type `string`. Primary image URL when the post includes a single primary image.
      - **imageUrls** (optional) — type `array`. Gallery image URLs when the post includes multiple images.
        - _items:_
          - type `string`; minLength: 1
      - **videoSdUrl** (optional) — type `string`. Standard-definition video URL when this post includes playable video.
      - **videoHdUrl** (optional) — type `string`. High-definition video URL when this post includes playable video.
      - **videoThumbnailUrl** (optional) — type `string`. Video thumbnail image URL when available.
      - **topComments** (optional) — type `array`. A small set of top comments when Facebook exposes them for the post.
        - _items:_
          - **id** (required) — type `string`; minLength: 1. Comment id.
          - **text** (required) — type `string`; nullable. Comment text when available.
          - **publishTime** (optional) — type `integer`. When the comment was published (Unix epoch seconds) when available.
          - **authorDisplayName** (optional) — type `string`; nullable. Display name for the comment author when available.
          - **authorId** (optional) — type `string`. Facebook id for the comment author when available.
          - **authorUrl** (optional) — type `string`; nullable. Public Facebook URL for the comment author when available.
  - **page** (required) — type `object`. Pagination state for the current response.
    - **nextCursor** (required) — type `string`; nullable. Cursor to pass as `cursor` in the next request when more posts are available.
    - **hasMore** (required) — type `boolean`. Whether another page of posts is available.
- **meta** (required) — type `object`. Metadata describing the request and billing outcome.
  - **requestId** (required) — type `string`; minLength: 1. Unique request identifier for tracing this API call.
  - **creditsCharged** (required) — type `integer`; minimum: 0. Credits charged for this request.
  - **version** (required) — type `string`; enum: v1. Public API version that served the response.

### Example JSON (first_page)

```json
{
  "data": {
    "posts": [
      {
        "id": "10244109500012284",
        "text": "Example post text.",
        "url": "https://www.facebook.com/example/posts/pfbid0example",
        "publishTime": 1775718956,
        "authorDisplayName": "Example Author",
        "authorShortName": "Example",
        "authorId": "100063669491743",
        "reactionCount": 12,
        "commentCount": 3,
        "videoViewCount": null,
        "imageUrl": "https://example.com/image.jpg",
        "topComments": [
          {
            "id": "Y29tbWVudDoxXzI=",
            "text": "Nice post!",
            "publishTime": 1775719000,
            "authorDisplayName": "Commenter",
            "authorId": "123456789",
            "authorUrl": null
          }
        ]
      }
    ],
    "page": {
      "nextCursor": "Cg8Ob3JnYW5pY19jdXJzb3IJAAABexample",
      "hasMore": true
    }
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Example JSON (paginated)

```json
{
  "data": {
    "posts": [
      {
        "id": "10244073632835627",
        "text": "Second page example.",
        "url": "https://www.facebook.com/example/posts/pfbid0page2",
        "authorDisplayName": "Example Author",
        "reactionCount": 6,
        "commentCount": 1
      }
    ],
    "page": {
      "nextCursor": "next-cursor-token",
      "hasMore": true
    }
  },
  "meta": {
    "requestId": "req_01example_page_2",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Example JSON (empty)

```json
{
  "data": {
    "posts": [],
    "page": {
      "nextCursor": null,
      "hasMore": false
    }
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Machine-readable error codes

When an error JSON body is returned, it may include one of these `error.code` values (derived from the OpenAPI schemas for this operation; additional codes may exist at runtime):

- `bad_request`

## Error handling & retries

Interpret HTTP status codes using the descriptions below. Do not assume a JSON body unless the OpenAPI schema defines one for that status.

- **400**: Invalid `url`, `pageId`, `cursor`, or bad request **Retry:** Fix the request; retrying the same invalid payload will not help.
- **401**: Missing or invalid API key **Retry:** Fix the API key first; retrying without changes will not help.
- **402**: Insufficient credits **Retry:** Do not retry without resolving billing/credits (retrying the same request will not help).
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed from the response (unexpected or invalid data). **Retry:** May be transient; a few retries with backoff are reasonable.
- **503**: Service temporarily unavailable; safe to retry with backoff. **Retry:** Usually safe to retry with exponential backoff and jitter.

### Suggested client defaults

- Send the API key using the `x-api-key` header on every request.
- On `503` (and sometimes `502`), retry with backoff; cap retries and surface a clear error to the user.
- On `402`, surface an actionable billing message rather than blind retries.

## Examples

### TypeScript SDK

```typescript
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const result = await client.facebook.getProfilePosts({
  url: "https://www.facebook.com/profile.php?id=61575098504636",
});

if (!result.ok) {
  console.error(result.error);
} else {
  console.log(result.value.data);
}
```

### Node.js

```javascript
const response = await fetch(
  "https://api.socialfetch.dev/v1/facebook/profiles/posts",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    }
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl "https://api.socialfetch.dev/v1/facebook/profiles/posts" \
  -H "x-api-key: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.get(
    "https://api.socialfetch.dev/v1/facebook/profiles/posts",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()
print(data)
```

### Example: next page (pagination)

After a successful response, if pagination is not finished, request the next page using `cursor` (URL-encode when composing the query string):

```javascript
const previous = await response.json();
const nextCursor = previous?.data?.page?.nextCursor;
const hasMore = previous?.data?.page?.hasMore;
if (!hasMore || nextCursor == null) {
  // no more pages
} else {
  const nextUrl = new URL("https://api.socialfetch.dev/v1/facebook/profiles/posts");
  nextUrl.searchParams.set("cursor", nextCursor);
  // optionally preserve sort: nextUrl.searchParams.set("sortBy", "latest");
  const nextResponse = await fetch(nextUrl.toString(), {
    headers: { "x-api-key": "YOUR_API_KEY" },
  });
  const nextData = await nextResponse.json();
}
```