> 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: Count threads by tab

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

## Count threads by tab

`GET /v1/threads/counts` - operationId `threads.counts`

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

Returns thread counts for the inbox tabs: email and LinkedIn threads, matched Instagram and WhatsApp chats while
those channels are on, and iMessage threads while the workspace's `imessage` flag is on. Use it for tab
badges and to know when to reload the thread list.

Name the tab with `status`, `folder`, `isArchived` and `isSaved`, the same way
`GET /v1/threads` takes them. `allCount` is the number of threads that list returns for the tab.
`accountsCount` and `campaignsCount` split the tab into threads linked to an account and threads from a
campaign, and `campaigns` lists every campaign with a thread in the inbox. `toReplyCount`,
`unreadCount`, `latestMessageAt` and `inboxChangedAt` ignore the tab. An email thread counts once
however many messages it has, and a LinkedIn, Instagram, WhatsApp or iMessage conversation is one thread.
Instagram, WhatsApp and iMessage threads never count in `campaignsCount` or `campaigns`.

To keep a view current, poll this call and reload the list when `inboxChangedAt` changes. It moves when a
reply arrives, a late one included, and when a reply changes tab, for example when Kenso classifies it.

With `groupBy=person` the counts count people instead of threads, each the number of rows
`GET /v1/threads?groupBy=person` lists for the tab. A person counts under the campaign or account of their
thread in the tab. On a tab that lists your own sends (`folder=sent` or `folder=all`),
`allCount`, `accountsCount`, `campaignsCount` and `campaigns[].threadCount` keep counting
threads, because that grouped list's total can be capped. `toReplyCount` and `unreadCount` count people
on every tab.

`facebookUnreadCount` counts Facebook threads with an unread inbound message, and is omitted when Facebook
outreach is off for the workspace.

Errors:

- `400 validation_failed`: `status`, `folder` or `groupBy` is not a known value.

Requires Inbox view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string | no | The inbox tab to count: `to_reply`, `other`, `automated_reply`, `not_interested` or `human_reply`. Omit it to count threads of every status. |
| `folder` | query | string | no | Which messages to count: `inbox` (messages received), `sent` (messages sent) or `all` (both). Default `inbox`. |
| `isArchived` | query | boolean | no | Filters by archive state: `true` counts only archived threads and `false` only threads not archived. Kenso counts both when it is omitted or when `status=human_reply`. |
| `isSaved` | query | boolean | no | Filters by saved state: `true` counts only saved threads and `false` only threads not saved. Kenso counts both when it is omitted or when `status=human_reply`. |
| `groupBy` | query | string | no | Set to `person` to count distinct people instead of threads, one per row of `GET /v1/threads?groupBy=person`. Omit it to count threads, and any other value answers `400 validation_failed`. |
| `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 `ThreadCounts`.

| Field | Type | Description |
| --- | --- | --- |
| `allCount` | integer (int64) | Threads in the requested tab: the number `GET /v1/threads` lists with the same tab filters. With `groupBy=person`, people. |
| `accountsCount` | integer (int64) | Threads in the requested tab that are linked to an account. With `groupBy=person`, people. |
| `campaignsCount` | integer (int64) | Threads in the requested tab that belong to a campaign. With `groupBy=person`, people. |
| `campaigns` | array of ThreadCampaignCount | Every campaign with a thread in the inbox, the most recent activity first. A campaign with no thread in the requested tab has `threadCount` 0. |
| `toReplyCount` | integer (int64) | Threads on the To Reply tab, whatever tab you request. With `groupBy=person`, people. |
| `unreadCount` | integer (int64) | Threads with an unread inbound message, whatever tab you request. With `groupBy=person`, people. |
| `latestMessageAt` | string (date-time) | When the newest inbound message arrived, in UTC. Omitted when the inbox is empty. |
| `inboxChangedAt` | string (date-time) | When the inbox last changed, in UTC. An inbound email that arrives or changes moves it, such as a reply that syncs late, a reply Kenso moves to another tab, or a read. So does a change to a LinkedIn conversation whose last message is inbound, and to an Instagram, WhatsApp or iMessage chat the counts cover. It is not a message time. Poll it and reload the list when it changes. Omitted when the inbox is empty. |
| `facebookUnreadCount` | integer (int64) | Facebook threads with an unread inbound message. Omitted when Facebook outreach is off for the workspace. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/threads/counts" \
  -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": {
    "allCount": 42,
    "accountsCount": 6,
    "campaignsCount": 40,
    "campaigns": [
      {
        "campaignId": 4821,
        "campaignName": "Q4 SaaS founders",
        "threadCount": 40
      }
    ],
    "toReplyCount": 7,
    "unreadCount": 3,
    "latestMessageAt": "2026-10-13T16:22:05Z",
    "inboxChangedAt": "2026-10-13T16:22:05Z"
  }
}
```

## Types

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

### ThreadCampaignCount

One campaign's thread count in the requested tab.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignId` | integer (int64) | no | The campaign's id. |
| `campaignName` | string | no | The campaign's name. Omitted when the campaign has no name. |
| `threadCount` | integer (int64) | no | The campaign's threads in the requested tab, 0 when none are in it. With `groupBy=person`, people. |
