# Conversation threads

Inbox-scoped conversation metadata and paginated message context.

Source: https://cherami.to/docs/api/threads



Both routes require bearer authentication. Threads are automatic; no creation request is needed. They contain ready received messages and sent attempts, including rejected and unknown outcomes.

## List threads [#list-threads]

`GET /v1/inboxes/{inbox_id}/threads?limit=20` returns `200`:

```json
{
  "threads": [{
    "id": "44444444-4444-4444-8444-444444444444",
    "inbox_id": "11111111-1111-4111-8111-111111111111",
    "subject": "Review ready",
    "last_activity_at": "2026-10-01T00:00:00.000Z",
    "message_count": 3,
    "received_count": 1,
    "accepted_count": 1,
    "rejected_count": 0,
    "unknown_count": 1
  }],
  "next_cursor": null
}
```

Most recent activity first. `subject` is from the earliest surviving message and can be null. Counts include attempts, not just successful correspondence. These are metadata, not AI summaries.

## Read a thread [#read-a-thread]

`GET /v1/threads/{thread_id}?limit=20` returns `200` with the same thread metadata, plus `messages` and `next_cursor`.

Each entry has `direction` (`received` or `sent`), `timestamp` (ISO service receipt/submission time), and the fields from [received detail](https://cherami.to/docs/api/messages#read-a-message) or [sent detail](https://cherami.to/docs/api/sending#read-a-sent-message).

Bodies and attachment metadata are included, without attachment bytes. Received attachments use the ordinary download endpoint. Sent thread attachments have `id`, `filename`, `mime_type`, and `size` in bytes; use ordinary sent detail for their base64 content.

The first page contains the newest messages, **chronological within the page**. The next page contains older messages. Metadata counts describe the conversation, not just the current page.

## Pagination and changes [#pagination-and-changes]

Both routes accept `limit` 1–100, default 20. Follow `next_cursor` as a URL-encoded `cursor` parameter on the same resource URL. Ordering uses service timestamps, not sender-controlled Date headers.

Conversations can update, and pages are not a snapshot. Previously returned thread IDs remain usable while their conversation exists; the returned `id` may differ from the requested one. Continue a pagination sequence on the same requested URL, and refetch recent context when needed.

Pending, processing, and failed received messages have `thread_id: null` and are absent from threads. They remain available through message endpoints. Deleted messages disappear; surviving messages remain grouped. Empty, missing, or other-account conversations return `404`. Invalid limits/cursors return `400`, and unavailable content can return `503`.

No thread-wide deletion, manual merging, search, labels, or quote stripping is provided. Thread membership is not proof of identity or delivery. Reply using a message resource ID, not the thread ID.