# Read a conversation GET /v1/threads/{thread_id} Source: https://cherami.to/docs/api/threads/get-thread {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `GET /v1/threads/{thread_id}` Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. `GET /v1/threads/{thread_id}?limit=20` returns `200` with conversation 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/get-message) or [sent detail](https://cherami.to/docs/api/sending/get-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. Accepts `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`. Each message retains its own `labels`; threads have no label set. Filters select conversations without filtering their detail pages. Manual merging is not provided. Thread membership is not proof of identity or delivery. Reply using a message resource ID, not the thread ID. ## Parameters [#parameters] | Parameter | Location | Required | Type | Meaning | | ----------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `thread_id` | path | Yes | string | Owned Cherami resource ID returned by the API. | | `limit` | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. `minimum`: `1` `maximum`: `100` `default`: `20` | | `cursor` | query | No | string | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next\_cursor is null. | ## curl example [#curl-example] Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment. ```sh curl --silent --show-error --include --request GET \ "https://cherami.to/v1/threads/THREAD_ID" \ --header "Authorization: Bearer $CHERAMI_API_KEY" ``` ## Responses [#responses] ### HTTP 200 [#http-200] Successful operation; inspect resource state and outcome fields. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [ThreadDetail](#schema-threaddetail) ```json { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "subject": null, "last_activity_at": "2026-10-01T00:00:00.000Z", "message_count": 0, "received_count": 0, "accepted_count": 0, "rejected_count": 0, "unknown_count": 0, "messages": [], "next_cursor": null } ``` ### HTTP 400 [#http-400] `invalid_limit`: Use an integer from 1 to 100. `invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid\_draft. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 401 [#http-401] `unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost. * `X-Request-ID`: Support correlation ID, not an idempotency key. * `WWW-Authenticate`: `"Bearer"` Content type: `application/json`. [Error](#schema-error) ### HTTP 404 [#http-404] `not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 500 [#http-500] `internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 503 [#http-503] `content_unavailable`: Expected stored content is unavailable. Retry the read later. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ## Schema: ThreadDetail [#schema-threaddetail] | Field | Required | Type | Meaning and constraints | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `inbox_id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `subject` | Yes | string or null | | | `last_activity_at` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `message_count` | Yes | integer | `minimum`: `0` | | `received_count` | Yes | integer | `minimum`: `0` | | `accepted_count` | Yes | integer | `minimum`: `0` | | `rejected_count` | Yes | integer | `minimum`: `0` | | `unknown_count` | Yes | integer | `minimum`: `0` | | `messages` | Yes | array of [ThreadReceivedDetail](#schema-threadreceiveddetail) or [ThreadSentDetail](#schema-threadsentdetail) | | | `next_cursor` | Yes | string or null | | ## Schema: ThreadReceivedDetail [#schema-threadreceiveddetail] All of these schemas apply. ### Part 1 [#part-1] [ReceivedDetail](#schema-receiveddetail) ### Part 2 [#part-2] | Field | Required | Type | Meaning and constraints | | ----------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `direction` | Yes | `"received"` | | | `timestamp` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | ## Schema: ReceivedDetail [#schema-receiveddetail] Exactly one of these shapes applies. ### Alternative 1 [#alternative-1] | Field | Required | Type | Meaning and constraints | | ------------------- | -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `inbox_id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `thread_id` | Yes | string or null | | | `envelope_from` | Yes | string | | | `envelope_to` | Yes | string | | | `subject` | Yes | string or null | | | `received_at` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `processing_status` | Yes | `"ready"` | | | `labels` | Yes | array of string | | | `message_id` | Yes | string or null | | | `raw_size` | Yes | integer | `minimum`: `0` | | `processed_at` | Yes | string or null | | | `content` | Yes | [ReceivedContent](#schema-receivedcontent) | | ### Alternative 2 [#alternative-2] | Field | Required | Type | Meaning and constraints | | ------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `inbox_id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `thread_id` | Yes | string or null | | | `envelope_from` | Yes | string | | | `envelope_to` | Yes | string | | | `subject` | Yes | string or null | | | `received_at` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `processing_status` | Yes | `"pending"` or `"processing"` or `"failed"` | | | `labels` | Yes | array of string | | | `message_id` | Yes | string or null | | | `raw_size` | Yes | integer | `minimum`: `0` | | `processed_at` | Yes | string or null | | ## Schema: ReceivedContent [#schema-receivedcontent] | Field | Required | Type | Meaning and constraints | | ------------- | -------- | --------------------------------------------------------- | ----------------------- | | `from` | Yes | [ParsedAddress](#schema-parsedaddress) or null | | | `sender` | Yes | [ParsedAddress](#schema-parsedaddress) or null | | | `reply_to` | Yes | array of [ParsedAddress](#schema-parsedaddress) | | | `to` | Yes | array of [ParsedAddress](#schema-parsedaddress) | | | `cc` | Yes | array of [ParsedAddress](#schema-parsedaddress) | | | `bcc` | Yes | array of [ParsedAddress](#schema-parsedaddress) | | | `subject` | Yes | string or null | | | `message_id` | Yes | string or null | | | `in_reply_to` | Yes | string or null | | | `references` | Yes | string or null | | | `date` | Yes | string or null | | | `reply_text` | Yes | string or null | | | `text` | Yes | string or null | | | `html` | Yes | string or null | | | `attachments` | Yes | array of [ReceivedAttachment](#schema-receivedattachment) | | ## Schema: ParsedAddress [#schema-parsedaddress] Sender-controlled MIME address or group, not verified identity. Exactly one of these shapes applies. ### Alternative 1 [#alternative-1-1] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | ----------------------- | | `name` | Yes | string | | | `address` | Yes | string | | ### Alternative 2 [#alternative-2-1] | Field | Required | Type | Meaning and constraints | | ------- | -------- | --------------- | ----------------------- | | `name` | Yes | string | | | `group` | Yes | array of object | | #### `group` fields [#group-fields] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | ----------------------- | | `name` | Yes | string | | | `address` | Yes | string | | ## Schema: ReceivedAttachment [#schema-receivedattachment] | Field | Required | Type | Meaning and constraints | | ------------- | -------- | -------------- | ----------------------- | | `id` | Yes | string | | | `filename` | Yes | string or null | | | `size` | Yes | integer | `minimum`: `0` | | `mime_type` | Yes | string | | | `disposition` | Yes | string or null | | | `content_id` | Yes | string or null | | | `related` | Yes | boolean | | ## Schema: ThreadSentDetail [#schema-threadsentdetail] | Field | Required | Type | Meaning and constraints | | --------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `inbox_id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `created_at` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `recipient_count` | Yes | integer | `minimum`: `0` | | `status` | Yes | `"accepted"` or `"rejected"` or `"unknown"` | | | `provider_message_id` | Yes | string or null | | | `error_code` | Yes | string or null | | | `thread_id` | Yes | string or null | | | `in_reply_to` | Yes | string or null | | | `labels` | Yes | array of string | | | `direction` | Yes | `"sent"` | | | `timestamp` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `reply_text` | Yes | string or null | | | `submission` | Yes | object | | ### `submission` fields [#submission-fields] | Field | Required | Type | Meaning and constraints | | ------------- | -------- | --------------------------------------------- | ----------------------- | | `to` | Yes | array of [Mailbox](#schema-mailbox) or string | | | `cc` | Yes | array of [Mailbox](#schema-mailbox) or string | | | `bcc` | Yes | array of [Mailbox](#schema-mailbox) or string | | | `subject` | Yes | string | | | `text` | Yes | string | | | `html` | No | string | | | `attachments` | Yes | array of object | | | `from` | Yes | [Mailbox](#schema-mailbox) or string | | | `headers` | No | object | | #### `attachments` fields [#attachments-fields] | Field | Required | Type | Meaning and constraints | | ----------- | -------- | ------- | ----------------------- | | `id` | Yes | string | | | `filename` | Yes | string | | | `mime_type` | Yes | string | | | `size` | Yes | integer | `minimum`: `0` | #### `headers` fields [#headers-fields] | Field | Required | Type | Meaning and constraints | | ------------- | -------- | ------ | ----------------------- | | `In-Reply-To` | Yes | string | | | `References` | Yes | string | | ## Schema: Mailbox [#schema-mailbox] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `address` | Yes | string | Bare ASCII address, at most 254 characters, local part at most 64. No display-name header syntax. `maxLength`: `254` | | `name` | No | string | Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming. `x-max-utf8-bytes`: `256` | Unknown fields are rejected. ## Schema: Error [#schema-error] | Field | Required | Type | Meaning and constraints | | ------- | -------- | ------ | ----------------------- | | `error` | Yes | object | | ### `error` fields [#error-fields] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | --------------------------------------------------------------------------------------------- | | `code` | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. | | `message` | Yes | string | Human-readable context, not a stable string to match. | [HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)