# User posts

> An account's latest posts and reposts, newest first, with text, media and engagement counts.

- **Request:** `GET https://api.lurkapi.com/v1/bluesky/user/posts`
- **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard))
- **Cost:** 1 credit per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)).
- **MCP tool:** `bluesky_user_posts` on `https://api.lurkapi.com/mcp`
- **Freshness:** responses are cached for up to 3 minutes
- **Try it live:** https://lurkapi.com/docs/bluesky/user-posts#try (no signup; free tool: [Bluesky viewer](https://lurkapi.com/free-tools/bluesky-viewer))
- **Platform:** [Bluesky](https://lurkapi.com/docs/bluesky.md) (bsky.app)
- **Web page:** https://lurkapi.com/docs/bluesky/user-posts

## When to use this

Use it to track what an account posts and how it lands: likes, reposts, replies and quotes on every post. The default `filter` matches the Posts tab on bsky.app: posts, reposts and the account's own threads, without replies to others, with the pinned post first (`pinned: true`). Reposts have `repost: true` and the original poster as `author`.

Pass `handle` or `user_id`.

Accounts that opted out of logged-out visibility return 403 `not_public`, including empty feeds. Posts and reposts by hidden authors are omitted; hidden quotes are null. Visibility of the requested account is checked with a 30-second cached profile lookup.

**Pagination.** Up to 50 posts per page. Pass the response's `cursor` back as `cursor` (with the same account and filter); it's null at the end. Unknown, deactivated and suspended accounts return 404 `not_found`.

## Parameters

All parameters go in the query string.

| Name | Type | Required | Default | Allowed values | Description | Example |
| --- | --- | --- | --- | --- | --- | --- |
| `handle` | string | no |  |  | Handle (e.g. `bsky.app`), a DID or the profile URL. Required unless you pass `user_id`. | `bsky.app` |
| `user_id` | string | no |  |  | The account's DID, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`. Required unless you pass `handle`. |  |
| `filter` | string | no | `posts_and_author_threads` | `posts_and_author_threads`, `posts_with_replies`, `posts_no_replies`, `posts_with_media`, `posts_with_video` | `posts_and_author_threads` (the Posts tab), `posts_with_replies`, `posts_no_replies`, `posts_with_media` or `posts_with_video`. |  |
| `cursor` | string | no |  |  | The `cursor` from the previous response, to get the next page. |  |

## Example request

Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard).

curl:

```bash
curl "https://api.lurkapi.com/v1/bluesky/user/posts?handle=bsky.app" \
  -H "x-api-key: YOUR_API_KEY"
```

JavaScript:

```js
const params = new URLSearchParams({
  handle: "bsky.app",
});
const res = await fetch(`https://api.lurkapi.com/v1/bluesky/user/posts?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.posts);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/bluesky/user/posts",
    params={
        "handle": "bsky.app",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["posts"])
```

## Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in `…`.

200 OK (application/json):

```json
{
  "success": true,
  "credits_remaining": 999987,
  "credits_charged": 1,
  "posts": [
    {
      "uri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l",
      "cid": "bafyreicnt42y6vo6pfpvyro234ac4o6ijug6adwwrh7awflgrqlt4zibxq",
      "url": "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l",
      "text": "👋  Bluesky is an open social network that gives creators independence f…",
      "createdAt": "2024-10-17T07:06:51.491Z",
      "author": {
        "did": "did:plc:z72i7hdynmk6r22z27h6tvur",
        "handle": "bsky.app",
        "displayName": "Bluesky",
        "avatar": "https://cdn.bsky.app/img/avatar/plain/did:plc:z72i7hdynmk6r22z27h6tvur/b…"
      },
      "replyCount": 8621,
      "repostCount": 9536,
      "likeCount": 63723,
      "quoteCount": 711,
      "bookmarkCount": 256,
      "langs": [
        "en"
      ],
      "images": [],
      "video": null,
      "external": null,
      "quote": null,
      "links": [],
      "mentions": [],
      "tags": [],
      "replyTo": null,
      "repost": false,
      "pinned": true
    },
    {
      "uri": "at://did:plc:kwxpje5qog6wwndagwbssatp/app.bsky.feed.post/3mviutosqmk2t",
      "cid": "bafyreigyzxfb3tynf6hus4cshhzcrwr7sht4vfp2l5phbbfephvn7bcd7a",
      "url": "https://bsky.app/profile/avclub.com/post/3mviutosqmk2t",
      "text": "Less than 4 hours until the #Emmys kick off! You can keep up with all th…",
      "createdAt": "2026-09-14T19:47:12.655Z",
      "author": {
        "did": "did:plc:kwxpje5qog6wwndagwbssatp",
        "handle": "avclub.com",
        "displayName": "The A.V. Club",
        "avatar": "https://cdn.bsky.app/img/avatar/plain/did:plc:kwxpje5qog6wwndagwbssatp/b…"
      },
      "replyCount": 31,
      "repostCount": 37,
      "likeCount": 525,
      "quoteCount": 4,
      "bookmarkCount": 26,
      "langs": [
        "en"
      ],
      "images": [
        {
          "thumbnail": "https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:kwxpje5qog6wwndagw…",
          "fullsize": "https://cdn.bsky.app/img/feed_fullsize/plain/did:plc:kwxpje5qog6wwndagwb…",
          "alt": ""
        }
      ],
      "video": null,
      "external": null,
      "quote": null,
      "links": [
        "https://bsky.app/profile/avclub.com/feed/emmys-watch-r"
      ],
      "mentions": [
        "bsky.app"
      ],
      "tags": [
        "Emmys"
      ],
      "replyTo": null,
      "repost": true,
      "pinned": false
    }
  ],
  "cursor": "2026-08-26T14:31:49.108Z"
}
```

## Response fields

Every field of a successful response. `[]` marks a list: `a[].b` is the `b` of each item in `a`. **nullable** fields can be `null`; **optional** fields can be missing.

| Field | Type | Description |
| --- | --- | --- |
| `success` | `true` | Always true here; errors have `success: false`. |
| `credits_remaining` | `number` | Your balance after this call. On anonymous playground calls: free tries left today. |
| `credits_charged` | `number` | Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1). |
| `posts` | `object[]` | One page of posts, newest first (the pinned post leads the first page). |
| `posts[].uri` | `string` | The post's `at://` URI, its permanent id. |
| `posts[].cid` | `string` | Content hash of this version of the post. |
| `posts[].url` | `string` | The post on bsky.app. |
| `posts[].text` | `string` | Post text. Empty for media-only posts. |
| `posts[].createdAt` | `string` | When it was posted, ISO 8601. |
| `posts[].author` | `object` | Who posted it. |
| `posts[].author.did` | `string` | The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`. |
| `posts[].author.handle` | `string` | Handle, e.g. `bsky.app`. It can change; the DID doesn't. |
| `posts[].author.displayName` | `string`, nullable | Display name; null if not set. |
| `posts[].author.avatar` | `string`, nullable | Avatar image URL; null if none. |
| `posts[].replyCount` | `number` | Replies. |
| `posts[].repostCount` | `number` | Reposts. |
| `posts[].likeCount` | `number` | Likes. |
| `posts[].quoteCount` | `number` | Quote posts. |
| `posts[].bookmarkCount` | `number` | Times saved to bookmarks. |
| `posts[].langs` | `string[]` | Languages the author tagged, e.g. `en`. |
| `posts[].images` | `object[]` | Attached images, in order. Empty if none. |
| `posts[].images[].thumbnail` | `string` | Small image URL. |
| `posts[].images[].fullsize` | `string` | Full-size image URL. |
| `posts[].images[].alt` | `string` | Alt text; empty if none. |
| `posts[].video` | `object`, nullable | Attached video; null if none. |
| `posts[].video.playlist` | `string` | HLS playlist (.m3u8) URL. |
| `posts[].video.thumbnail` | `string`, nullable | Poster image URL; null if none. |
| `posts[].video.alt` | `string`, nullable | Alt text; null if none. |
| `posts[].external` | `object`, nullable | Link card; null if none. |
| `posts[].external.uri` | `string` | The linked page. |
| `posts[].external.title` | `string` | Link card title. |
| `posts[].external.description` | `string` | Link card description. |
| `posts[].external.thumbnail` | `string`, nullable | Link card image URL; null if none. |
| `posts[].quote` | `object`, nullable | The post this one quotes; null if none or hidden from logged-out visitors. Embedded lists, feeds and starter packs aren't returned. |
| `posts[].quote.uri` | `string` | The quoted post's `at://` URI. Pass it as `url` to the post endpoint. |
| `posts[].quote.url` | `string` | The quoted post on bsky.app. |
| `posts[].quote.text` | `string`, nullable | Its text; null when it was deleted or its author blocks viewers. |
| `posts[].quote.createdAt` | `string`, nullable | When it was posted, ISO 8601; null when unavailable. |
| `posts[].quote.author` | `object`, nullable | Who posted it; null when unavailable. |
| `posts[].quote.author.did` | `string` | The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`. |
| `posts[].quote.author.handle` | `string` | Handle, e.g. `bsky.app`. It can change; the DID doesn't. |
| `posts[].quote.author.displayName` | `string`, nullable | Display name; null if not set. |
| `posts[].quote.author.avatar` | `string`, nullable | Avatar image URL; null if none. |
| `posts[].links` | `string[]` | Links in the text. |
| `posts[].mentions` | `string[]` | Handles mentioned in the text, without @. |
| `posts[].tags` | `string[]` | Hashtags in the text, without #. |
| `posts[].replyTo` | `string`, nullable | `at://` URI of the post this replies to; null for top-level posts. |
| `posts[].repost` | `boolean` | A repost by this account; `author` is the original poster. |
| `posts[].pinned` | `boolean` | The account's pinned post, shown first on the first page. |
| `cursor` | `string`, nullable | Pass as `cursor` for the next page. null on the last page. |

## Pagination

Pass the response's `cursor` back as `cursor`, with the other parameters unchanged, for the next page. It's `null` on the last page. Each page costs 1 credit.

The first five pages, in JavaScript:

```js
let cursor = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ handle: "bsky.app" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.lurkapi.com/v1/bluesky/user/posts?${params}`, {
    headers: { "x-api-key": process.env.LURKAPI_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(`${data.code}: ${data.error}`);
  console.log(data.posts);
  cursor = data.cursor;
  if (!cursor) break; // last page
}
```

## Caching and freshness

Responses are cached for up to 3 minutes, so a repeat call within that window can return the same data. It still costs 1 credit.

## Errors

Errors return `{ success: false, error, code, docs }` with the HTTP status below. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors).

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `missing_api_key` | No API key. Send it in the `x-api-key` header. |
| 401 | `invalid_api_key` | The key is unknown or was revoked. |
| 402 | `insufficient_credits` | Not enough credits for this call. Buy a pack or wait for tomorrow's top-up. |
| 403 | `not_public` | The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target. Charged when the platform was checked. |
| 404 | `not_found` | The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked. |
| 405 | `method_not_allowed` | Endpoints take GET with query params. |
| 429 | `rate_limited` | Too many calls at once. Wait for the `retry-after` seconds, then retry. |
| 500 | `internal_error` | Something broke on our side. Retry; 5xx errors are free. |
| 502 | `upstream_error` | The platform didn't give a usable answer. Retry; 5xx errors are free. |
| 503 | `upstream_busy` | All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free. |
| 504 | `upstream_timeout` | The platform took over 30 seconds to answer. Retry; timeouts are free. |

## Use it in Claude

Once LurkAPI is [connected to Claude](https://lurkapi.com/docs.md#claude), this endpoint is the `bluesky_user_posts` tool. Ask in plain English, for example:

Ask Claude:

```text
Use LurkAPI's bluesky_user_posts with handle "bsky.app" and summarize what you find.
```

Claude calls `bluesky_user_posts` with arguments like these, and each call costs 1 credit:

Tool arguments:

```json
{
  "handle": "bsky.app"
}
```

Tool results skip nulls and empty lists to save tokens.

---

Previous: [Profile](https://lurkapi.com/docs/bluesky/profile.md) · Next: [Post](https://lurkapi.com/docs/bluesky/post.md)