> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/threads/openapi.json](/docs/api/threads/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Threads: List a thread's messages

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Threads](/docs/api/threads.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## List a thread's messages

`GET /v1/threads/{threadId}/messages` - operationId `threads.list-messages`

| Permission | Rate limit |
| --- | --- |
| Inbox view | 12,000 requests a minute per API key |

Returns every message in a thread, oldest first, in one page. Each item carries `kind`: `message` for an
email or chat message.

With `includeEvents=true` a LinkedIn thread also lists the connection note sent with the invitation
(`connection_note`, outbound) and the moment the person accepted (`connection_accepted`, inbound, with
an empty body), in time order. An event comes before a message sent at the same instant. An email thread ignores
`includeEvents`. When Kenso cannot read the events, it returns the messages alone.

Errors:

- `404 not_found`: the id is malformed, or no thread in this workspace has it.

Requires Inbox view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/threads/GET/v1/threads/%7BthreadId%7D/messages)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `threadId` | path | string | yes | The thread's `thr_` id. |
| `includeEvents` | query | boolean | no | True to add a LinkedIn thread's connection events to its messages. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `ThreadMessage`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The message's `msg_` id. |
| `threadId` | string | The `thr_` id of the thread. |
| `channel` | string | The channel: `email`, `linkedin`, `instagram`, `facebook`, `whatsapp` or `imessage`. |
| `kind` | string | What the item is: `message` for an email or chat message. A LinkedIn thread read with `includeEvents=true` also lists `connection_note` (the note sent with the invitation, outbound) and `connection_accepted` (the accept, inbound, with an empty body). An Instagram chat also has `story_reply` and `story_mention` (a message about a story), and `notice`: an event Instagram writes into the chat (for example that the person cannot receive the message), with no sender. Always set. |
| `direction` | string | Who sent the message: `inbound` (the contact) or `outbound` (the workspace). |
| `subject` | string | The message's subject. Null when it has none. |
| `body` | string | The message text. |
| `extractedText` | string | Inbound email only: the sender's own words, without quoted history, signature, mobile footer and sign-off. Omitted for outbound email, for LinkedIn, and for a message with no readable body. `body` keeps the full text. |
| `language` | string | Inbound messages only: the message's language as an ISO 639-1 code, such as `en`. Omitted when unknown and on outbound messages. |
| `occurredAt` | string (date-time) | When the message was sent or received, in UTC. |
| `scheduledMessageId` | integer (int64) | On the response of `POST /v1/threads/{threadId}/messages`, email only: the queued reply's scheduled message id. Until its undo window ends, `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` with this id stops it. Omitted otherwise. |
| `warnings` | array of ThreadMessageWarning | Set on `POST /v1/threads/{threadId}/messages` when the reply went out past a safeguard you confirmed, and on `POST /v1/threads` when the new thread went out from an inbox that has not finished warmup. Omitted otherwise. |
| `senderName` | string | The same value as `fromName`. |
| `fromName` | string | The sender's name. |
| `fromEmailAddress` | string | Email only: the sender's address. |
| `htmlBody` | string | Email only: the message as HTML. |
| `tags` | array of ThreadTag | The tags on the message. |
| `to` | array of ThreadRecipient | Email only: the To recipients. |
| `cc` | array of ThreadRecipient | Email only: the Cc recipients. |
| `bcc` | array of ThreadRecipient | Email only: the Bcc recipients. |
| `openCount` | integer (int32) | Outbound email only: opens of the tracking pixel, without known proxies and crawlers. 0 when not opened or not tracked. |
| `rawOpenCount` | integer (int32) | Outbound email only: every hit on the tracking pixel, proxies and prefetches included. Always at least `openCount`. |
| `firstOpenedAt` | string (date-time) | Outbound email only: the first recorded open, in UTC. |
| `lastOpenedAt` | string (date-time) | Outbound email only: the latest recorded open, in UTC. |
| `referral` | ThreadReferral | Inbound email only: the person a recruiting reply referred you to, when its interest is `referral`. Null on LinkedIn messages and every other reply. |
| `browserRun` | ThreadBrowserRun | The workflow browser run whose web form submission this inbound message answers, or null. The Kenso app labels such a message as a browser run and never counts it as a reply. |
| `attachments` | array of MessageAttachment | Email only, on `GET /v1/threads/{threadId}/messages`: the message's files, inline images included. Download one with `GET /v1/attachments/{attachmentId}/content`. Omitted when the message has none. |
| `voiceNote` | VoiceNoteRef | LinkedIn only: the message's voice note. A note Kenso sent carries its `voiceNoteId`, the script and, while Kenso keeps the audio, `audioUrl`. A contact's note carries `voiceNoteId` 0, status `received` and `durationMs`. A note the account owner sent from LinkedIn itself is the same with status `sent`. Omitted otherwise. |
| `voiceTranscript` | string | WhatsApp only: the transcript of a voice note the contact sent, when one was made. Omitted otherwise. |
| `imessage` | ThreadMessageImessage | iMessage only: delivery, failure, tapbacks and media. Omitted on other channels. |
| `sentBy` | string | Email only: `agent` when Ken sent this message, either the reply agent (a reply a client approved first included) or a workflow's reply step, so the thread shows it as sent by Ken. Omitted on a message a person sent. |
| `agentJobId` | integer (int64) | The reply-agent job whose draft went out as this message, rated as `reply_job:{agentJobId}` on the `reply_sent` surface. Omitted when `sentBy` is, or when the job is not known. |
| `quoteDroppedReason` | string | Outbound email only: set when a reply or 1:1 follow-up went out without the earlier message Kenso quotes below it, because that message would have put a Kenso link in cold email. `brand_domain_in_quote`: the earlier message itself loads from a Kenso host or carries a Kenso tracking link. `brand_domain_when_joined`: each passes on its own, but the reply and the quote joined load from a Kenso host. The reply itself went out as written. Omitted when the quote went out, and on messages sent before Kenso recorded it. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20/messages" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
      "threadId": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
      "channel": "email",
      "kind": "message",
      "direction": "inbound",
      "subject": "Re: Onboarding new engineers at Northwind Labs",
      "body": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?\n\nAmanda\n\nOn Tue, Oct 13, 2026 at 9:04 AM Alex Rivera <alex@mail.example.com> wrote:\n> Hi Amanda, following up on this.",
      "extractedText": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?",
      "language": "en",
      "occurredAt": "2026-10-13T16:22:05Z",
      "senderName": "Amanda Chen",
      "fromName": "Amanda Chen",
      "fromEmailAddress": "amanda.chen@northwind.example.com",
      "htmlBody": "<p>Thanks Alex, this is timely. We are hiring 12 engineers this quarter.</p><p>Could we talk Thursday afternoon?</p><p>Amanda</p>",
      "tags": [
        {
          "id": 341,
          "name": "Hot lead",
          "color": "#FFD6A5"
        }
      ],
      "to": [
        {
          "name": "Alex Rivera",
          "address": "alex@mail.example.com"
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### ThreadMessageWarning

A warning on a message that went out.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | What the warning is about: `suppressed_contact_overridden` (on a reply) or `warmup_not_ready` (on a new thread). |
| `reason` | string | no | With `suppressed_contact_overridden`, the suppression reason: `do_not_contact`, `blocklisted` or `unsubscribed`. With `warmup_not_ready`, the warmup state: `too_young` or `unconfirmed`. |
| `fix` | string | no | With `warmup_not_ready`: what to do. The email was sent, so pick an inbox that finished warmup for the next one. |
| `readyAt` | string (date-time) | no | With `warmup_not_ready` and `too_young`: the day the inbox is ready, in UTC. |

### ThreadTag

A tag on a thread or message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The tag's id. |
| `name` | string | no | The tag's name. |
| `color` | string | no | The tag's display color. |
| `systemKey` | string | no | Set on a built-in Kenso tag: a fixed key to find it by, which stays the same when its name changes. Null on the workspace's own tags. |

### ThreadRecipient

An email recipient.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The display name. Null when the email gives none. |
| `address` | string | no | The email address. |

### ThreadReferral

The person a recruiting reply referred you to, when its interest is `referral`. Every part comes from the reply itself, and a part the reply does not give is null.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The person's name. |
| `email` | string | no | The person's email address. |
| `linkedinUrl` | string | no | The person's LinkedIn profile URL. |
| `phone` | string | no | The person's phone number as the reply writes it. Kenso cannot add a person with only a phone number as a contact, so add them by hand. |

### ThreadBrowserRun

The workflow browser run whose web form submission a thread or message answers.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `runId` | string | no | The browser run's id, as a string. |
| `automated` | boolean | no | True when the headers and the sender show that a machine sent the email, such as a form confirmation or a notification. |

### MessageAttachment

A file on an email message, inline images included.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The `att_` id that `GET /v1/attachments/{attachmentId}/content` downloads. Omitted when Kenso cannot serve the file, as for an older message whose original email Kenso did not store. |
| `fileName` | string | no | The file name the email gives. Null when it gives none. |
| `contentType` | string | no | The MIME type the email gives, such as `image/png`. |
| `sizeBytes` | integer (int64) | no | The file size in bytes. Null when unknown. |
| `isInline` | boolean | no | True for a part the email shows in its body, such as an inline image. |
| `contentId` | string | no | The MIME Content-ID an HTML body's `cid:` image refers to, without the `cid:` scheme. |

### VoiceNoteRef

A LinkedIn voice note on a message, touch or account activity. `audioUrl` is an API route that redirects to a short-lived link to the audio, and is set only while Kenso keeps the audio.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceNoteId` | integer (int64) | no | The voice note's id. 0 for a voice note a contact sent. |
| `status` | string | no | `pending`, `generating`, `ready`, `sent`, `failed` or `expired`. On a thread message, a contact's note reads `received`. |
| `durationMs` | integer (int32) | no | The audio's length in milliseconds. Null until known. |
| `language` | string | no | The language of the script. Null when unknown. |
| `provider` | string | no | The voice service that made the audio. Null when unknown. |
| `voiceId` | string | no | The voice used for the audio. Null when unknown. |
| `scriptText` | string | no | The words spoken. Null until generated, and left out of list reads. |
| `failureReason` | string | no | Why the voice note failed. Null unless status is `failed`. |
| `audioAvailable` | boolean | no | True while Kenso keeps the audio. |
| `audioUrl` | string | no | The API route that serves the audio. Null when the audio is gone. |

### ThreadMessageImessage

One iMessage text's delivery, failure, tapbacks and media.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deliveredChannel` | string | no | How the text was delivered: `imessage` or `sms`. Omitted until delivered. |
| `deliveredAt` | string (date-time) | no | When the text was delivered. Omitted until delivered. |
| `failedAt` | string (date-time) | no | When delivery failed. Omitted unless it failed. |
| `errorCode` | string | no | A code for why delivery failed. Omitted unless it failed. |
| `reactions` | array of ThreadImessageReaction | no | The tapbacks on the text, at most one per direction (`inbound`: the person's, `outbound`: yours). |
| `mediaCount` | integer (int32) | no | How many images the text carried. |
| `voiceNoteId` | integer (int64) | no | The voice note the text carried; `GET /v1/voice-notes/{voiceNoteId}/imessage-audio` plays it. Omitted when none. |
| `attachments` | array of ThreadImessageAttachment | no | Files the person sent with an inbound text. Each file's `url` is a Kenso route that downloads it. |

### ThreadImessageReaction

A tapback on an iMessage text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `direction` | string | no | `inbound` (the person's) or `outbound` (yours). |
| `value` | string | no | love, like, dislike, laugh, emphasize, question, or one emoji. |
| `at` | string (date-time) | no | When the tapback was set. |

### ThreadImessageAttachment

A file on an inbound iMessage text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contentType` | string | no | The file's MIME type, when known. |
| `fileName` | string | no | The file's name, when known. |
| `url` | string | no | Where the file downloads: `GET /v1/threads/{threadId}/messages/{messageId}/attachments/{index}`, where `index` is the file's 0-based position in `attachments`. Requires Inbox view. Omitted when Kenso has no link for the file. |
