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

# Conversation history

> Read a conversation's messages for context with cursor pagination.

Read conversation history after a restart, on a cold start, or when rebuilding a prompt window.

Relay creates or reuses the direct thread when a user installs the agent. See [Conversation lifecycle](/guides/conversation-lifecycle) for membership, removal, and reinstall behavior.

```bash theme={null}
curl -sS "https://api.relayapp.im/v1/conversations/cnv_01JZC7K4RQ/messages?limit=50" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

Messages return **newest first** with ordered `parts[]`, `sequence`, `reply_to`,
reactions, revision history, and a receipt-projected `status` (`sent`,
`delivered`, or `read`):

```json theme={null}
{
  "messages": [
    {
      "id": "msg_01JZM4Q9VN",
      "conversation_id": "cnv_01JZC7K4RQ",
      "sequence": 2,
      "sender": { "kind": "agent", "id": "agt_01JZRELAY" },
      "parts": [{ "part_index": 0, "type": "text", "text": "Tomorrow at 2:00 PM works." }],
      "reply_to": { "message_id": "msg_01JZM3T8AH", "part_index": 0 },
      "reactions": [],
      "fallback_text": "Tomorrow at 2:00 PM works.",
      "status": "read",
      "edited_at": "2026-07-12T01:21:12.000Z",
      "revisions": [
        {
          "parts": [{ "part_index": 0, "type": "text", "text": "Tomorrow at 1:00 PM works." }],
          "fallback_text": "Tomorrow at 1:00 PM works.",
          "replaced_at": "2026-07-12T01:21:12.000Z"
        }
      ],
      "created_at": "2026-07-12T01:21:08.000Z"
    }
  ]
}
```

`revisions` is ordered from oldest to newest and is empty for a message that
has never been edited. Each entry preserves the prior canonical parts and
fallback text. `edited_at` is present after the first edit.

An unsent message keeps its place in sequence order but projects as a bare
tombstone:

```json theme={null}
{
  "id": "msg_01K1M9UNSENT",
  "conversation_id": "cnv_01JZC7K4RQ",
  "sequence": 3,
  "sender": { "kind": "user", "id": "usr_01JZU1F0BD" },
  "status": "deleted",
  "created_at": "2026-07-12T01:21:10.000Z"
}
```

Tombstones do not expose parts, fallback text, reactions, or revisions.

## Pagination

`limit` accepts 1–100 and defaults to 50. To page backward, pass your lowest `sequence` as `before_sequence`.

```bash theme={null}
curl -sS ".../messages?before_sequence=2&limit=50" ...
```

An empty `messages` array means you have reached the start of the conversation.

## Notes

Message `status` includes the delivery and read watermark projected for the message's recipients. See [Read receipts](/guides/read-receipts) for the lifecycle.

* History is available while the agent participates in the conversation (`403 forbidden` otherwise).
* `sequence` orders messages *within one conversation*. It is unrelated to a webhook `event_id`.
* History is the recovery path after an event gap or uncertain delivery.

## Next steps

* [Read receipts](/guides/read-receipts)
* [Delivery model](/guides/delivery-model)
* [Conversation lifecycle](/guides/conversation-lifecycle)