--- title: "Read a conversation" method: GET path: "/v1/threads/{thread_id}" tags: ["threads"] --- # Read a conversation `GET /v1/threads/{thread_id}` ## Request - Base URL: `https://cherami.to` - URL: `https://cherami.to/v1/threads/{thread_id}` - Auth: HTTP bearer Returns the conversation's metadata and its messages, with bodies and attachment metadata. Each message has `direction` (`received` or `sent`), `timestamp`, and the fields of [received](https://cherami.to/docs/api/messages/get-message) or [sent](https://cherami.to/docs/api/sending/get-sent-message) detail. The first page holds the newest messages, oldest first within the page; `next_cursor` fetches older ones. Order follows Cherami's receipt and send times, not the senders' Date headers. Counts describe the whole conversation. Attachment bytes aren't included: [download](https://cherami.to/docs/api/messages/download-attachment) a received file, or read [sent detail](https://cherami.to/docs/api/sending/get-sent-message) for a sent file's base64 content. Received messages that aren't ready, or failed, aren't part of a conversation; read them through the message endpoints. ## Path parameters - `thread_id` string, required ## Query parameters - `limit` integer - `cursor` string ## Response `200` Success. - ThreadDetail - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `subject` string, nullable, required - `last_activity_at` string, date-time, required: UTC timestamp with milliseconds. - `message_count` integer, required - `received_count` integer, required - `accepted_count` integer, required - `rejected_count` integer, required - `unknown_count` integer, required - `messages` union[], required - union - union - object - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `thread_id` string, nullable, required: Cherami resource ID. - `envelope_from` string, required - `envelope_to` string, required - `subject` string, nullable, required - `received_at` string, date-time, required: UTC timestamp with milliseconds. - `processing_status` 'ready', required - `labels` string[], required - `message_id` string, nullable, required: The message's Message-ID header, not a Cherami ID: reply and forward take id. - `raw_size` integer, required - `processed_at` string, date-time, nullable, required: UTC timestamp with milliseconds. - `content` ReceivedContent, required - `from` union, required: Mailbox or group from the message headers, written by the sender and not verified. - … - `sender` union, required: Mailbox or group from the message headers, written by the sender and not verified. - … - `reply_to` ParsedAddress[], required - … - `to` ParsedAddress[], required - … - `cc` ParsedAddress[], required - … - `bcc` ParsedAddress[], required - … - `subject` string, nullable, required - `message_id` string, nullable, required: Message-ID header as the sender wrote it. - `in_reply_to` string, nullable, required - `references` string, nullable, required - `date` string, nullable, required: The sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering. - `reply_text` string, nullable, required: New text without quoted history. Empty: there is none. Null: it couldn't be extracted. - `text` string, nullable, required - `html` string, nullable, required - `attachments` ReceivedAttachment[], required - … - `direction` 'received', required - `timestamp` string, date-time, required: UTC timestamp with milliseconds. - object - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `thread_id` string, nullable, required: Cherami resource ID. - `envelope_from` string, required - `envelope_to` string, required - `subject` string, nullable, required - `received_at` string, date-time, required: UTC timestamp with milliseconds. - `processing_status` 'pending' | 'processing' | 'failed', required - `labels` string[], required - `message_id` string, nullable, required: The message's Message-ID header, not a Cherami ID: reply and forward take id. - `raw_size` integer, required - `processed_at` string, date-time, nullable, required: UTC timestamp with milliseconds. - `direction` 'received', required - `timestamp` string, date-time, required: UTC timestamp with milliseconds. - ThreadSentDetail - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `created_at` string, date-time, required: UTC timestamp with milliseconds. - `recipient_count` integer, required - `status` 'accepted' | 'rejected' | 'unknown', required - `provider_message_id` string, nullable, required: Message-ID the provider assigned when it accepted the message. - `error_code` string, nullable, required: Reason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown. - `thread_id` string, nullable, required: Cherami resource ID. - `in_reply_to` string, nullable, required: Cherami resource ID. - `labels` string[], required - `direction` 'sent', required - `timestamp` string, date-time, required: UTC timestamp with milliseconds. - `reply_text` string, nullable, required: New text without quoted history. Empty: there is none. Null: it couldn't be extracted; read submission. - `submission` object, required - `to` union[], required - union - … - `cc` union[], required - union - … - `bcc` union[], required - union - … - `subject` string, required - `text` string, required - `html` string - `attachments` object[], required - `id` string, required - `filename` string, required - `mime_type` string, required - `size` integer, required - `from` union, required - Mailbox - … - string: Plain address string, as some older messages store it. - `headers` object - `In-Reply-To` string, required - `References` string, required - `next_cursor` string, nullable, required ## Other responses - `400`: `invalid_limit`: Use an integer from 1 to 100. `invalid_cursor`: Send a cursor only to the listing, filters and order that returned it, or restart from the first page. - `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer `. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery). - `404`: `not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox. - `500`: `internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes. - `503`: `content_unavailable`: Stored content could not be read. Retry later. --- [API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)