# Reading and engaging · PostLake Docs

> Markdown version of https://docs.postlake.dev/reading . The canonical page for humans.
> PostLake is the social media API for AI agents: https://postlake.dev/llms.txt

Publishing is half of managing an account. These endpoints cover the other half: what happened, what people said, and answering them.

MCP equivalents are `list_notifications`, `mark_notifications_seen`, `read_comments`, `reply_to_comment`, `engage`, and `update_profile`. See the [MCP guide](https://postlake.dev/mcp).

## What happened

`GET /v1/notifications` returns likes, replies, mentions, follows, reposts and quotes from every connected network, newest first, in one shape. It is the read to start from when an agent asks "what needs my attention".

```
curl https://api.postlake.dev/v1/notifications?limit=25 \
  -H "authorization: Bearer $POSTLAKE_KEY"
```

## Every list tells you what it could not read

Responses are `{ items, cursor, problems }`. `problems` is the important part. A network that is unreachable, unauthorised or simply not supported yet is named there, so an empty `items` never has to stand in for "we could not look".

```
{
  "items": [ ... ],
  "cursor": "eyJhY2Nf...",
  "problems": [
    { "platform": "tiktok", "reason": "We cannot read this on tiktok yet." }
  ]
}
```

 **Nothing found and could not look are different answers.** Check `problems` before concluding an account is quiet.

## Paging

Pass `cursor` back exactly as you got it. Never build or parse one: a cross-network read encodes a separate position per network inside it, and the contents will change. `cursor: null` means the end.

## Replies on a post

`GET /v1/posts/{id}/comments` reads the conversation under something you published, across every network it went to. Replies nest one level; going deeper is another call.

Add `?nested=true` to read the whole thread, replies to replies included. Networks that cannot go deeper answer with the top level instead of refusing, so it is always safe to ask.

Each reply carries `hidden`: `true` if you have hidden it, `false` if it is visible, and `null` where the network does not say. Treat `null` as "we cannot tell", not as "not hidden", or an agent will keep trying to hide the same reply.

## Hiding a reply

`POST /v1/comments/{id}/hide` hides a reply on one of your posts. Send `{"hidden": false}` to put it back.

```
curl -X POST https://api.postlake.dev/v1/comments/17901.../hide \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9"}'
```

This is the other half of replying. Without it, the only answer to an abusive comment is to write another one. If the call fails, the reply is **still visible**: treat an error as "still there", never as "probably fine".

Some networks will not let you hide your own reply. Threads is one, and it says so in the error rather than failing vaguely.

## Searching, and looking people up

Everything above reads your own corner of each network. `/v1/discover` reads the network itself, which is what lets an agent look before it speaks.

```
curl "https://api.postlake.dev/v1/discover/posts?q=social+media+api&sort=recent" \
  -H "authorization: Bearer $POSTLAKE_KEY"
```

| Endpoint | What it does |
| --- | --- |
| `GET /v1/discover/posts` | Search public posts by keyword, or by topic tag with `mode=tag`. Narrow with `sort`, `mediaType`, `author`, `since` and `until`. |
| `GET /v1/discover/profiles/{handle}` | Look someone up: name, bio, verified, follower count, and recent engagement where the network publishes it. |
| `GET /v1/discover/profiles/{handle}/posts` | Read someone else's public posts. |
| `GET /v1/discover/places` | Find a place to tag on a post, by name or by `latitude` and `longitude`. The id goes in that network's `locationId` option. |

Searching merges every connected network that can search, and names the ones that cannot in `problems`. The other three need an `account`, because the same handle on two networks is usually two different people and merging them would invent someone who does not exist.

Counts are `null` where a network does not publish them, never `0`. "We could not see it" and "they have none" are different answers.

## Engaging

One endpoint, one vocabulary. `POST /v1/engagements` takes an `action` of `like`, `unlike`, `repost`, `unrepost`, `follow`, `unfollow`, `block`, `unblock`, `mute` or `unmute`.

```
curl -X POST https://api.postlake.dev/v1/engagements \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9","action":"like","target":"https://bsky.app/profile/alice.bsky.social/post/3l..."}'
```

`target` is a post (a uri or its web url) for likes and reposts, or a handle for follows, blocks and mutes. Other networks are free. X actions spend funded credits according to the action.

## X billing and spending safeguards

X always uses PostLake's shared developer app. Customer-owned X app credentials are not supported. Stored analytics reports do not contact X or spend refresh credits.

 - Mentions and comments: 6 credits per returned provider row, including author lookup coverage.
- Followers: 4 credits per returned user. Message events: 8 credits per event, even when several events become one conversation.
- Post analytics: 4 credits per refresh attempt, covering up to two provider reads. Channel identity refresh: 4 credits.
- Replies cost 8 credits for text or 90 with a link. Thread parts and first comments are separate X posts; media alt-text metadata costs 2 credits per item.
- X operations reserve credits before contacting X. Free monthly grants cannot fund X. Unused read reservations return to their original monthly or pack buckets.
- Provider minimum page sizes apply: 5 mentions or 10 comments. A balance too small for that page is refused before the call.
- Daily safety reservations cap each workspace at 10,000 credits and the service at 50,000 credits, resetting by UTC day. Attempts count even when they fail. These safeguards are separate from ordinary request rate limits.

Read reservations settle against provider rows before filtering or grouping. Explicit rejected reads refund their reservation. An ambiguous network failure retains its reservation because the provider may already have incurred cost; contact support for reconciliation. Pricing does not assume X's app-owner Owned Reads discount for shared-app customers.

A network that does not support an action refuses and names what it does support, rather than quietly doing nothing. Check [the platform tables](https://postlake.dev/platforms) or `GET /v1/platforms` first.

## Which networks can do this

Inbox, engage and discovery depth varies by network. Implemented capabilities do not imply public connection access. Read `connectionAvailability` on `GET /v1/platforms` before offering a network. Purchasing credits does not unlock gated connections. The [platform support](https://postlake.dev/platforms) page lists implementation capabilities.