# Bluesky User Posts (`bluesky.user_posts`)

Recent posts from one Bluesky account, newest first, with engagement counts, media and cursor pagination.

Docs: https://primaryapi.com/docs/api-reference/bluesky/user_posts

- Endpoint: `POST https://api.primaryapi.com/v1/run/bluesky.user_posts`
- Category: Social · Platform: `bluesky` · Kind: list · Status: live
- Price: 1 credit per call; up to 2 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=bluesky.user_posts`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `handle` | string | yes |  | max 300 chars | Bluesky handle such as "bsky.app" (a bare name gets ".bsky.social"), with or without @, a did:plc: identifier, or a bsky.app profile URL. |
| `limit` | integer | no | 20 | 1–100 | Maximum number of results to return (1-100, default 20). |
| `cursor` | string | no |  |  | Opaque pagination cursor: pass the previous response's nextCursor. |
| `includeReposts` | boolean | no | true |  | Keep posts the account reposted from other accounts (default true). |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `posts` | object[] |  |
| `posts[].id` | string | Record key (last segment of the AT-URI) |
| `posts[].uri` | string | at:// URI |
| `posts[].url` | string | https://bsky.app/profile/{handle}/post/{id} |
| `posts[].text` | string \| null |  |
| `posts[].createdUtc` | string \| null | ISO 8601 creation time |
| `posts[].authorHandle` | string \| null |  |
| `posts[].authorName` | string \| null |  |
| `posts[].authorImage` | string \| null |  |
| `posts[].authorDid` | string \| null |  |
| `posts[].likes` | integer \| null |  |
| `posts[].replies` | integer \| null |  |
| `posts[].reposts` | integer \| null |  |
| `posts[].quotes` | integer \| null |  |
| `posts[].images` | string[] | Full-size image URLs |
| `posts[].externalUrl` | string \| null | Link-card target |
| `posts[].videoUrl` | string \| null | HLS playlist of an attached video |
| `posts[].isRepost` | boolean | The account reposted this post (author is someone else) |
| `posts[].repostedBy` | string \| null | Handle of the reposting account when isRepost |
| `nextCursor` | string \| null |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

Pagination: pass the previous response’s `nextCursor` as `cursor` to get the next page; `nextCursor: null` means there are no more results.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/bluesky.user_posts" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"bsky.app","limit":1,"includeReposts":false}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "posts": [
        {
          "id": "3mz4cvlf7z22v",
          "uri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3mz4cvlf7z22v",
          "url": "https://bsky.app/profile/bsky.app/post/3mz4cvlf7z22v",
          "text": "New in beta: the moderation inbox. \n\nNow you can see the reports you've made, and find out what happened to the content you reported, right in the Bluesky app. Notices about your account and appeals live there too.",
          "createdUtc": "2026-10-30T17:34:58.466Z",
          "authorHandle": "bsky.app",
          "authorName": "Bluesky",
          "authorImage": "https://cdn.bsky.app/img/avatar/plain/did:plc:z72i7hdynmk6r22z27h6tvur/bafkreihwihm6kpd6zuwhhlro75p5qks5qtrcu55jp3gddbfjsieiv7wuka",
          "authorDid": "did:plc:z72i7hdynmk6r22z27h6tvur",
          "likes": 1367,
          "replies": 66,
          "reposts": 258,
          "quotes": 70,
          "images": [
            "https://cdn.bsky.app/img/feed_fullsize/plain/did:plc:z72i7hdynmk6r22z27h6tvur/bafkreigxnoofflq3v4g3x54pk36v5pjtt2nb3imkxtknj7ieisguo527le"
          ],
          "externalUrl": null,
          "videoUrl": null,
          "isRepost": false,
          "repostedBy": null
        }
      ],
      "nextCursor": "eyJic2t5IjoiMjAyNi0xMC0zMFQxNzozNDo1OC40NjZaIn0"
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
  "nextCursor": null
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: up to 2 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=bluesky.user_posts`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Accounts that opted out of logged-out viewing are not served (reason "private").

## Legal

Returns public personal data (names, handles, avatars, post text). Callers need a lawful basis under GDPR/CCPA and must honour deletion requests.

