Skip to Content
Deliverability

Infrastructure findings

Infra findings are problems Kenso finds in a workspace's inboxes and domains, such as a disconnected inbox, a domain about to expire or a deleted mailbox that is still billed. Kenso checks every 6 hours, opens a finding for each new problem and resolves it once a later check no longer sees the problem. Use this section to count and list findings and to snooze, ignore or reopen one. A status change hides or shows a finding and changes nothing on the inbox or domain itself.

Deliverability3 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

List infra findings

GET/v1/infra/findingsinfra.findings
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Lists the workspace's infra findings, newest first. Without a status filter it returns open findings only.

Each filter takes one value or several separated by commas, and a finding matches when it has any of them. evidence holds what Kenso saw, and suggestedAction names the fix Kenso recommends.

Errors:

  • 400 validation_failed: a filter value is not one of its allowed values, limit is not from 1 to 200, or cursor is invalid.

Requires Delivery view.

Parameters

NameInTypeRequiredDescription
kindquerystringoptionalKinds to return, separated by commas: billing_leak, provider_cancelled, warmup_missing, idle_domain, domain_expiring, inbox_no_domain or disconnected_inbox. Omitted returns every kind.
statusquerystringoptionalStatuses to return, separated by commas: open, snoozed, ignored or resolved. Omitted returns open findings only.
severityquerystringoptionalSeverities to return, separated by commas: critical, warning or info. Omitted returns every severity.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
limitqueryinteger (int32)optionalFindings per page, from 1 to 200. Defaults to 50.
Request
curl -X GET "https://api.ken.so/v1/infra/findings?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

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

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update an infra finding

PATCH/v1/infra/findings/{findingId}infra.update-finding
Permission
Delivery edit
Rate limit
4,800 requests a minute per API key
Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Snoozes, ignores or reopens one finding. Use it to hide a finding you already know about. It changes nothing on the inbox, the domain or at a provider.

Send status: snoozed with snoozedUntil, ignored, or open to reopen the finding. A snoozed finding opens again at the first check after snoozedUntil. An ignored finding stays ignored until you reopen it, and Kenso never resolves it on its own. Kenso writes who made the change to the workspace's audit log. Returns the updated finding.

Errors:

  • 400 validation_failed: status is missing or not open, snoozed or ignored, or snoozedUntil is missing with snoozed, not in the future, more than a year ahead, or sent with another status.
  • 403 forbidden: the finding is a billing_leak. Kenso fixes those itself, so you cannot snooze or ignore one.
  • 404 not_found: the workspace has no finding with this id.
  • 409 invalid_state: the finding is resolved.

Requires Delivery edit.

Parameters

NameInTypeRequiredDescription
findingIdpathinteger (int64)requiredId of the finding.

Request body

application/json, optional.

FieldTypeRequiredDescription
statusstringrequiredNew status: snoozed, ignored, or open to reopen the finding. Required.
snoozedUntilstring (date-time)optionalWhen a snoozed finding opens again, as an ISO 8601 UTC timestamp in the future and at most a year ahead. Required with snoozed and refused with any other status.
Request
curl -X PATCH "https://api.ken.so/v1/infra/findings/812" \
  -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 '{
  "status": "snoozed",
  "snoozedUntil": "2026-09-23T15:02:11Z"
}'

Response 200

data is a InfraFinding.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get the infra summary

GET/v1/infra/summaryinfra.summary
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Counts the workspace's open and snoozed findings, with what the inboxes and domains behind them cost a month. Use it for a badge or a health overview before you list the findings.

openCount and bySeverity count open findings, and snoozedCount counts snoozed ones. Ignored and resolved findings are not counted. byKind has one entry for each kind with open findings. Money values cover only the inboxes and domains whose price Kenso knows, and their amount is in cents.

Requires Delivery view.

Request
curl -X GET "https://api.ken.so/v1/infra/summary" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a InfraSummary.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page