> 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: Get a thread

> **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).

## Get a thread

`GET /v1/threads/{threadId}` - operationId `threads.get`

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

Returns one thread. Read its messages with `GET /v1/threads/{threadId}/messages`.

An email thread also carries `scheduledMessages`: the replies and forwards queued on it that have not sent
yet, a reply that waits for a member's approval included. `POST /v1/scheduled-messages/{scheduledMessageId}/cancel`
withdraws one. `accountId` and `accountName` name the account whose touch the thread is, else the
account where the thread's contact is a stakeholder. An email thread of an account touch also carries
`replyTouchId`, the open reply touch that answers it.

A Facebook thread carries `historyStartsAt` while the account's history is locked.

A WhatsApp or iMessage thread's `contactId` is its person's newest contact, null when the person has none. An
iMessage thread's `inboxId` is its line's id.

Errors:

- `404 not_found`: the id is malformed, or no thread in this workspace has it.
- `500 internal_error`: Kenso could not load the thread, for example an iMessage thread's ready voice note: try
it again.

Requires Inbox view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `threadId` | path | string | yes | The thread's `thr_` id. |
| `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 `Thread`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The thread's `thr_` id. |
| `channel` | string | The channel: `email`, `linkedin`, `instagram`, `facebook`, `whatsapp` or `imessage`. |
| `direction` | string | Only on `GET /v1/threads`: who sent the newest message the row shows, `inbound` (the contact) or `outbound` (the workspace). On an outbound email row `fromName` is yours, so the contact is the first entry of `to`. A LinkedIn row's `fromName` is the contact either way. Omitted from a single thread and from updates, whose messages carry their own direction. |
| `campaignId` | integer (int64) | The campaign the thread belongs to. Null for a thread outside any campaign. |
| `contactId` | integer (int64) | The contact the thread is with. Null when Kenso matched no contact. |
| `accountId` | integer (int64) | The account the thread belongs to: the account whose touch the thread is. `GET /v1/threads/{threadId}` falls back to the account where the thread's contact is a stakeholder, matched by email, else LinkedIn URL. Omitted when there is none, when the account is outside the accounts the caller may see, or while the accounts feature is off for the caller. |
| `accountName` | string | The name of the `accountId` account. Omitted with it. |
| `replyTouchId` | integer (int64) | Email threads of an account touch, on lists and `GET /v1/threads/{threadId}`: the account's open reply touch that answers a message in this thread, the newest when there are several. Its status is `planned`, `drafted`, `awaiting_approval` or `approved`. Send the reply by approving the touch with `POST /v1/touches/{touchId}/approve`, so the account's plan records it. Omitted without `accountId`, on LinkedIn threads, when there is none or Kenso could not read it, and from updates. |
| `hasDraft` | boolean | True when a reply draft is saved on the thread, whoever wrote it. `GET /v1/threads/{threadId}/draft` returns it. False when Kenso could not read the draft. |
| `draftAuthor` | string | Who last wrote the draft: `user` (a person in the Kenso app) or `agent` (an agent or API key). Omitted without a draft. |
| `inboxId` | integer (int64) | The thread's inbox. For a LinkedIn thread, the LinkedIn account. For an iMessage thread, its line's id. For an email thread, the workspace inbox its message was sent to (a reply you received) or sent from (your own), even when that inbox was deleted since. On `GET /v1/threads` the message is the row's. On `GET /v1/threads/{threadId}` it is the newest inbound message, else the newest. Omitted when the message names no inbox of the workspace. |
| `subject` | string | The subject of the thread's email. Null when it has none. |
| `preview` | string | The newest message's text for a preview, or its HTML when it has no text part. |
| `isRead` | boolean | True when the thread is marked read. |
| `isArchived` | boolean | True when the thread is archived. |
| `isSaved` | boolean | True when the thread is saved. |
| `interest` | string | The label on the thread's newest reply: `interested`, `question`, `not_interested`, `negative`, `automated`, `unclassified`, `unsubscribe`, `objection`, `wrong_contact`, `referral`, `out_of_office`, `hard_bounce`, `soft_bounce`, `complaint`, `unknown` or `ndr` (a non-delivery report). `unclassified` when it has no label. |
| `reminderAt` | string (date-time) | When the reminder on the thread is due, in UTC. Null without a reminder. |
| `lastMessageAt` | string (date-time) | When the newest message was sent or received, in UTC. |
| `waitingSince` | string (date-time) | Only on `GET /v1/threads`: when the contact's newest message arrived, on any tab. It is a wait on your reply only on the To Reply tab: a thread marked done or archived still carries it. A thread you answered whose reminder came due is on To Reply for that reminder, so it carries the reminder's due time. Omitted when the newest message is yours and no reminder is due. |
| `updatedAt` | string (date-time) | When the thread last changed, in UTC. |
| `senderName` | string | The same value as `fromName`. |
| `fromName` | string | Email: the name of the newest message's sender, yours when that message is outbound. LinkedIn: the contact's name, omitted when the conversation names nobody. |
| `fromEmailAddress` | string | Email only: the address of the newest message's sender. |
| `htmlBody` | string | Email only: the newest message's body as HTML. |
| `tags` | array of ThreadTag | The tags on the thread. |
| `to` | array of ThreadRecipient | Email only: the newest message's To recipients. |
| `cc` | array of ThreadRecipient | Email only: the newest message's Cc recipients. |
| `bcc` | array of ThreadRecipient | Email only: the newest message's Bcc recipients. |
| `scheduledMessages` | array of ScheduledMessage | Only on `GET /v1/threads/{threadId}` for an email thread: the replies and forwards queued on this thread that have not sent yet, in `scheduled`, `sending` or `awaiting_approval` status, the soonest due first. An empty list means none are pending. Omitted from lists, from updates, and when Kenso could not read them. |
| `referral` | ThreadReferral | The person a recruiting reply referred you to, when its `interest` is `referral`. Set on `GET /v1/threads/{threadId}` for an email thread. Null on lists, on LinkedIn threads and for every other reply. |
| `browserRun` | ThreadBrowserRun | The workflow browser run whose web form submission this thread answers, or null. Set on `GET /v1/threads` rows and `GET /v1/threads/{threadId}`. The Kenso app labels such a thread as a browser run and never counts it as a reply. |
| `language` | string | The language of the newest inbound message, as an ISO 639-1 code such as `en`. On `GET /v1/threads` an email row carries its own message's, so a row whose newest message is yours has none. Omitted when unknown. |
| `imessage` | ThreadImessage | iMessage only: the line, the number, whether the person replied (images and voice notes need it) and whether the thread goes by SMS (text only). Omitted on other channels. |
| `historyStartsAt` | string (date-time) | Facebook only: the oldest point this thread's history reaches while the account's history is locked. Omitted once it is unlocked and on every other channel. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20" \
  -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": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
    "channel": "email",
    "direction": "inbound",
    "campaignId": 4821,
    "contactId": 90125,
    "hasDraft": false,
    "inboxId": 5530,
    "subject": "Re: Onboarding new engineers at Northwind Labs",
    "preview": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?",
    "isRead": false,
    "isArchived": false,
    "isSaved": false,
    "interest": "interested",
    "lastMessageAt": "2026-10-13T16:22:05Z",
    "waitingSince": "2026-10-13T16:22:05Z",
    "updatedAt": "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"
      }
    ],
    "language": "en"
  }
}
```

## Types

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

### 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. |

### ScheduledMessage

An email reply or forward that Kenso queued to send after its undo window.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The scheduled message's id. `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` takes it. |
| `messageId` | string | no | The `msg_` id of the message it replies to or forwards. |
| `kind` | string | no | The kind of message: `reply` or `forward`. |
| `status` | string | no | The message's status: `scheduled`, `sending`, `sent`, `cancelled`, `failed` or `awaiting_approval`. |
| `approverMemberId` | integer (int64) | no | With status `awaiting_approval`: the member who must approve the message before it sends, the owner of the sending mailbox. `GET /v1/members` gives their name. |
| `delaySeconds` | integer (int32) | no | The undo window in seconds, 60 or 300. |
| `sendAt` | string (date-time) | no | When Kenso sends the message, in UTC. |
| `createdAt` | string (date-time) | no | When Kenso queued the message, in UTC. |
| `body` | string | no | The message's body. |
| `senderEmailId` | integer (int32) | no | The id of the inbox that sends the message. |
| `to` | array of ThreadRecipient | no | The To recipients. Null when none were named. |
| `cc` | array of ThreadRecipient | no | The Cc recipients. Null when none were named. |
| `bcc` | array of ThreadRecipient | no | The Bcc recipients. Null when none were named. |
| `draft` | ScheduledMessageDraft | no | On a cancel: the message, saved back as the thread's draft. |

### 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. |

### ThreadImessage

An iMessage thread's line, number and reply state.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lineId` | integer (int64) | no | The workspace's iMessage line the thread is on (`GET /v1/imessage-lines/{lineId}`). |
| `phone` | string | no | The person's number in E.164 (`+14155550100`). |
| `hasReplied` | boolean | no | The person texted this line at least once. Images and voice notes go only after that. |
| `isSmsThread` | boolean | no | The thread goes by SMS (green bubbles): text only, no images or voice notes. A tapback there arrives as a text, so only a member sends one; an agent's or API key's is `409` `imessage_sms_thread`. |
| `personId` | integer (int64) | no | The person the conversation is with: the `personId` to make a voice note for this thread with (`POST /v1/voice-notes`). Omitted when the conversation has no person. |
| `isNameless` | boolean | no | No name was found for the person on this thread, so the thread's `fromName` and `senderName` are their number. Show the thread as a conversation with an unknown person. |
| `voiceNoteInProgress` | ThreadVoiceNoteInProgress | no | The voice note Kenso is making for this thread right now (`POST /v1/voice-notes` with this thread's `threadId`), so the app can show it being made after a reload instead of starting a second one. Poll it with `GET /v1/voice-notes/{voiceNoteId}`. Omitted when none is being made. |
| `ownerName` | string | no | The member who owns the thread's line: texts on this thread go out in their name. Their first and last name, else their email. Omitted when the owner's account is gone. |
| `ownerLeft` | boolean | no | The line's owner can't send from it anymore (they are no longer an active member of the workspace, or are a network member), so nothing goes on this thread until an admin gives the line a new owner in Delivery. Always false for a released or failed line. |
| `voiceNoteReady` | ThreadVoiceNoteReady | no | The newest voice note you made for this thread in the last 30 minutes (`POST /v1/voice-notes` with this thread's `threadId`, or with neither a touch nor a thread while this was the person's latest thread) that is ready and not sent yet, so a create that timed out on your side but finished is offered instead of made and charged again. Only a note the calling member asked for (`createdByMemberId`); never another member's, and none for an API key with no member. Only on a single thread (`GET /v1/threads/{threadId}` and the thread an update returns), never on a list row; omitted when there is none. A read that fails fails the thread read (500 `internal_error`), so a missing field always means there is no such note. |

### ScheduledMessageDraft

A cancelled message, saved back as the thread's draft.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | no | The `msg_` id of the message the draft replies to or forwards. |
| `kind` | string | no | The kind of message: `reply` or `forward`. |
| `body` | string | no | The draft's body. |
| `senderEmailId` | integer (int32) | no | The id of the inbox the draft sends from. |
| `to` | array of ThreadRecipient | no | The draft's To recipients. Null when none. |
| `cc` | array of ThreadRecipient | no | The draft's Cc recipients. Null when none. |
| `bcc` | array of ThreadRecipient | no | The draft's Bcc recipients. Null when none. |
| `saved` | boolean | no | False when the cancel went through but Kenso could not save this draft as the thread's draft. The draft is still here, so save it yourself. |

### ThreadVoiceNoteInProgress

A voice note being made for an iMessage thread.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The voice note's id. |
| `status` | string | no | Its status: `generating` while it is being made. |
| `createdByMemberId` | integer (int64) | no | The member who asked for it, as their member id. Omitted for a note an API key with no member asked for. |

### ThreadVoiceNoteReady

A ready voice note made for an iMessage thread and not sent yet.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceNoteId` | integer (int64) | no | The voice note's id: send it as the `voiceNoteId` of a reply, or read it with `GET /v1/voice-notes/{voiceNoteId}`. |
| `createdAt` | string (date-time) | no | When the note was asked for. |
| `createdByMemberId` | integer (int64) | no | The member who asked for it, as their member id. Omitted for a note an API key with no member asked for. |
| `durationMs` | integer (int32) | no | The note's length in milliseconds. Omitted when it was not measured. |
