> 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: Update many threads

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

## Update many threads

`POST /v1/threads/bulk-update` - operationId `threads.bulk-update`

| Permission | Rate limit |
| --- | --- |
| Inbox edit | 480 requests a minute per API key |

Applies the same change to up to 1,000 threads. The body is a JSON object with `ids`, a list of `thr_`
ids, and the fields to change, under the same rules as `PATCH /v1/threads/{threadId}`. `personId` is
not allowed here: link people one thread at a time.

Kenso updates each thread on its own, so one failure does not stop the others. The response lists the ids that
changed in `succeeded` and the rest in `failed`, each with the error `code` the `PATCH` answers
for that thread: `not_found`, `validation_failed`, or `internal_error` when Kenso could not update it
for a fault of its own (try it again), and the `PATCH`'s `details` when it has any. A field with a bad
value fails every well-formed id with `validation_failed` (a malformed id stays `not_found`). An iMessage
`interest` refusal carries detail `imessage_no_inbound` (no text from the person yet) or
`imessage_newer_text` (a newer text arrived first: reload the thread and set it again). An iMessage thread
whose `unsubscribe` opt-out could not be written fails with `internal_error`, and part of that opt-out may
already stand, as on `PATCH /v1/threads/{threadId}`. An iMessage thread already gone when Kenso checks it
(`not_found`) or with no text from the person (`imessage_no_inbound`) fails before its opt-out and gets
none; one that a new text (`imessage_newer_text`) or a delete (`not_found`) reaches while its opt-out is
written fails and keeps the opt-out. Retry failed ids in a new request (a new `Idempotency-Key`, or none: the
same key replays this answer for 24 hours).

Errors:

- `400 validation_failed`: `ids` is missing, empty, longer than 1,000 or holds a value that is not a
string, the body has no field to change, or it sets `personId`.
- `403 forbidden`: the caller is a workspace key and the body sets `interest`, as on a single thread.

Requires Inbox edit.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isRead` | boolean | no | True marks the thread read, false unread. Null is refused. |
| `isArchived` | boolean | no | True archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused. |
| `isSaved` | boolean | no | True saves the thread, false takes it out of the saved threads. Null is refused. |
| `interest` | string | no | The label: `interested`, `not_interested`, `negative`, `automated`, `unclassified`, `unsubscribe`, `objection`, `wrong_contact`, `referral` or `out_of_office`. `not_interested` reads back as `negative`, and a LinkedIn thread does not take `automated`. On an email thread, any value but `automated`, `out_of_office` and `unclassified` marks the reply as written by a person and stops the contact's sequence. Null is refused. |
| `reminderAt` | string (date-time) | no | When to remind you, as an ISO 8601 instant. Null clears the reminder. |
| `ids` | array of string | yes | Required. From 1 to 1,000 `thr_` thread ids. |

### Response 200

`data` is a `ThreadBulkResult`.

| Field | Type | Description |
| --- | --- | --- |
| `succeeded` | array of string | The `thr_` ids Kenso updated. |
| `failed` | array of ThreadBulkFailure | The ids Kenso could not update, each with its error. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/threads/bulk-update" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
    "thr_ZW1haWw6NDAyMzE3LjFAZXhhbXBsZS5jb20"
  ],
  "isRead": true,
  "isArchived": true,
  "isSaved": false,
  "interest": "out_of_office"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "succeeded": [
      "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20"
    ],
    "failed": [
      {
        "id": "thr_ZW1haWw6NDAyMzE3LjFAZXhhbXBsZS5jb20",
        "error": {
          "code": "not_found",
          "message": "No thread with this id in the workspace."
        }
      }
    ]
  }
}
```

## Types

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

### ThreadBulkFailure

A thread a bulk update could not change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The id as you sent it. |
| `error` | ThreadBulkError | no | Why the update failed. |

### ThreadBulkError

Why one thread in a bulk update failed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | The error code, as `PATCH /v1/threads/{threadId}` answers it for that thread: `not_found`, `validation_failed`, or `internal_error` when Kenso could not update it for a fault of its own (try it again in a new request: the same `Idempotency-Key` replays this answer for 24 hours). |
| `message` | string | no | A readable explanation. |
| `details` | array of ErrorDetail | no | What failed, as `error.details` of the same `PATCH` names it: each item's `field` and detail `code`. On an iMessage thread an `interest` refusal names `imessage_no_inbound` (the person has not texted the thread yet) or `imessage_newer_text` (a newer text from them arrived first: reload the thread and set it again in a new request). Omitted when the failure has no detail. |

### ErrorDetail

One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields appear only with the codes their descriptions name.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | no | The request field, header or limit the problem is about, such as `name` or `Ken-Version`. |
| `code` | string | no | Stable code for this problem, such as `required` or `invalid`. |
| `message` | string | no | A sentence for people that explains this problem. |
| `count` | integer (int32) | no | On `export_limit_exceeded`, how many rows match the export. Omitted otherwise. |
| `index` | integer (int32) | no | The position of the refused item in the request's list. Omitted otherwise. |
| `limit` | integer (int32) | no | On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose `field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate limits, the limit that was hit. Omitted otherwise. |
| `resetAt` | string (date-time) | no | On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level `quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets. Omitted otherwise. |
| `retryAfterSeconds` | integer (int32) | no | On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the same value as the `Retry-After` header. Omitted otherwise. |
| `inboxId` | integer (int64) | no | The inbox the problem is about. Omitted otherwise. |
| `domainId` | integer (int64) | no | The domain the problem is about. Omitted otherwise. |
| `domainName` | string | no | The name of that domain, or the domain name the request gave. Omitted otherwise. |
| `accountId` | integer (int64) | no | On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use instead. Omitted otherwise. |
| `personId` | integer (int64) | no | On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise. |
| `stakeholderId` | integer (int64) | no | The account stakeholder the problem is about. Omitted otherwise. |
| `championId` | integer (int64) | no | Not used. Always omitted. |
| `callTaskId` | integer (int64) | no | On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise. |
| `status` | string | no | On `invalid_transition`, the current status. Omitted otherwise. |
| `allowed` | array of string | no | On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed from. Omitted otherwise. |
| `scope` | string | no | On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On `sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise. |
| `removedAt` | string (date-time) | no | On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise. |
| `page` | string | no | On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise. |
| `required` | string | no | On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise. |
| `feature` | string | no | On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise. |
| `runId` | integer (int64) | no | On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted otherwise. |
| `mergedIntoId` | integer (int64) | no | On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the merged account now lives on. Omitted otherwise. |
| `accounts` | array of ErrorAccount | no | On `person_on_accounts`, the accounts that block the change. Omitted otherwise. |
| `stage` | string | no | On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise. |
| `opportunityCount` | integer (int32) | no | On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise. |
| `rule` | string | no | On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise. |
| `nextAllowedAt` | string (date-time) | no | On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused send, when to retry. Omitted otherwise, and when waiting does not clear it. |
| `fix` | string | no | On a refused send, what to do next, in plain words. Omitted otherwise. |
| `opensAt` | string (date-time) | no | On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise. |
| `currentVersion` | integer (int32) | no | On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise. |
| `provider` | string | no | On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`, `account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise. |
| `sharedWithMaster` | boolean | no | True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so `limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent. |
| `stepId` | integer (int64) | no | On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and for a step the save would have created. |
| `stepOrder` | integer (int32) | no | On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise. |
| `url` | string | no | On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise. |
| `key` | string | no | On `unfilled_template_key`, the template key the text still holds, such as `first_name` for `{first_name}`. Omitted otherwise. |
| `marker` | string | no | On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`. Omitted otherwise. |
| `retryAt` | string (date-time) | no | On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`, `guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted otherwise. |
| `workspaceId` | integer (int64) | no | On `last_admin`, a workspace that needs a new admin before the account can be deleted. On `new_admin_not_found`, the workspace of the refused choice. Omitted otherwise. |
| `workspaceName` | string | no | On `last_admin`, the name of that workspace. Omitted otherwise. |
| `class` | string | no | On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit: `read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise. |
| `window` | string | no | On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted otherwise. |

### ErrorAccount

An account named in an error detail.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | integer (int64) | no | The account's id. |
| `name` | string | no | The account's name. |
| `stakeholderId` | integer (int64) | no | The person's stakeholder id on this account. |
