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

# Credits

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

Your credit balance.

Workspace and account. 1 endpoint under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/credits/openapi.json](/docs/api/credits/openapi.json).

- `GET /v1/credits` - Get the credit balance (`credits.get`): [/docs/api/credits/get.md](/docs/api/credits/get.md)

## Get the credit balance

`GET /v1/credits` - operationId `credits.get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns the workspace's credit balance: what is left, what data and AI work can spend now, the plan's included
sends and free builds, and any bonus credits or launch offer. A white-label client workspace sees its parent
workspace's shared balance.

A member without the `billing` permission gets the response without its billing details:
`includedMillicredits`, `purchasedMillicredits`, `debtMillicredits`,
`reservedMonthlyMillicredits`, `includedExpiresAt`, `grandfatheredUntil`, `autoTopUp`,
`reservedItems`, `pendingCreditPurchases` and `unpaidRenewals`.

`smtpSending` is present while SMTP inboxes are billed per email: `millicreditsPerEmail` is the price of
one campaign email sent from such an inbox, `inboxesPerDomain`, `startDailyLimit`, `dailyStep` and
`maxDailyLimit` are the limits of an SMTP inbox, and `paused` is true while the workspace has an SMTP
domain billed per email and the credits it bought cannot pay for one email: those sends wait until credits are
bought (a plan's included credits and bonus or free credits do not pay for SMTP emails), while
Google and Outlook inboxes keep sending. Every member gets it. It is absent otherwise.

Open to any workspace member.

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

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

### Response 200

`data` is a `CreditBalance`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `credit_balance`. |
| `balanceMillicredits` | integer (int64) | The credits left minus any debt. |
| `includedMillicredits` | integer (int64) | Included plan credits left, which expire. A billing detail. |
| `purchasedMillicredits` | integer (int64) | Purchased, granted and other credits that do not expire. A billing detail. |
| `bonusMillicredits` | integer (int64) | Bonus credits left from a credit promotion. Kenso spends them before the included credits, they expire at the end of their billing month, and they cannot pay for Kenso inboxes, domains or iMessage lines unless the workspace is exempt or Kenso staff allowed its free credits for them. |
| `bonusExpiresAt` | string (date-time) | When the earliest bonus credits left expire. Omitted when none are left. |
| `bonusPromotion` | CreditBonusPromotion | The workspace's running credit promotion. Omitted when it has none or the promotion ended. |
| `debtMillicredits` | integer (int64) | Usage that no credits covered yet. The next credits added repay it first. A billing detail. |
| `reservedMonthlyMillicredits` | integer (int64) | The monthly cost of active monthly items, such as Kenso inboxes, domains, LinkedIn accounts and iMessage lines, held back for their renewals. A billing detail. |
| `availableMillicredits` | integer (int64) | What data and AI work can spend now: the balance minus `reservedMonthlyMillicredits`. |
| `inboxDomainEligibleMillicredits` | integer (int64) | What can pay for Kenso inboxes, domains and iMessage lines: the balance minus free and bonus credits, which cannot. Equal to the balance when the workspace is exempt or Kenso allowed its free credits for them. |
| `freeMillicredits` | integer (int64) | Free credits left: signup, bonus, Kenso-granted free credits and rewards. They count in the balance and pay for data, AI and sending, but cannot pay for Kenso inboxes, domains or iMessage lines unless the workspace is exempt or Kenso staff allowed its free credits for them. Includes `bonusMillicredits`. |
| `includedExpiresAt` | string (date-time) | When the earliest included credits left expire. Omitted when none are left. A billing detail. |
| `monthlyIncludedCredits` | integer (int32) | Credits the plan grants each billing month. |
| `usdPerCredit` | string | The price of one credit in US dollars, as a string such as `"0.02"`. |
| `exempt` | boolean | True when Kenso records costs on the ledger but never charges them. |
| `creditState` | string | The balance state: `healthy`, `low` under 500 available credits, or `out` when data and AI work cannot start because nothing is available or a white-label client workspace hit its cap. Sending and warmup keep running, and an exempt workspace is always `healthy`. |
| `exhaustedAt` | string (date-time) | When available credits last dropped to zero or below. Omitted while credits are available. |
| `grandfatheredUntil` | string (date-time) | Until when an older plan keeps its earlier allowance. Omitted otherwise. A billing detail. |
| `sends` | CreditSends | Included sends this billing month. |
| `builds` | CreditBuilds | Free campaign builds this billing month. |
| `autoTopUp` | CreditAutoTopUp | The rule that buys credits when they run low. A billing detail. |
| `reservedItems` | array of CreditReservedItem | Active monthly items, such as Kenso inboxes, by credit action. A billing detail. |
| `pendingCreditPurchases` | array of CreditPendingPurchase | Bank debit purchases still processing, oldest first. Kenso adds their credits when the payment clears. A billing detail. |
| `unpaidRenewals` | array of CreditUnpaidRenewal | Monthly items, such as Kenso inboxes, domains, LinkedIn accounts and iMessage lines, whose renewal went unpaid, oldest first. A billing detail. |
| `launchOffer` | CreditLaunchOffer | The launch offer of a paid, non-exempt workspace while its window is open: email finding and profile enrichment cost no credits until `endsAt`, up to `limit` lookups. Omitted otherwise. |
| `smtpSending` | CreditSmtpSending | SMTP inboxes billed per email: what one campaign email costs, the limits of such an inbox, and whether sending from them is paused because the credits the workspace bought cannot pay for one email. Omitted while per-email SMTP billing is off. |
| `aiLimit` | CreditAiLimit | The AI limit while the workspace is on the new pricing with the AI limit enforced; omitted otherwise. Percent and state only, never dollars. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/credits" \
  -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": {
    "object": "string",
    "balanceMillicredits": 1,
    "includedMillicredits": 1,
    "purchasedMillicredits": 1,
    "bonusMillicredits": 1,
    "bonusExpiresAt": "2026-09-23T15:02:11Z",
    "bonusPromotion": {
      "code": "EWOR",
      "monthlyCredits": 1,
      "endsAt": "2026-09-23T15:02:11Z"
    },
    "debtMillicredits": 1,
    "reservedMonthlyMillicredits": 1,
    "availableMillicredits": 1,
    "inboxDomainEligibleMillicredits": 1,
    "freeMillicredits": 1,
    "includedExpiresAt": "2026-09-23T15:02:11Z",
    "monthlyIncludedCredits": 1,
    "usdPerCredit": "string",
    "exempt": true,
    "creditState": "string",
    "exhaustedAt": "2026-09-23T15:02:11Z",
    "grandfatheredUntil": "2026-09-23T15:02:11Z",
    "sends": {
      "includedPerPeriod": 1,
      "usedThisPeriod": 1,
      "periodStart": "2026-09-23T15:02:11Z",
      "periodEnd": "2026-09-23T15:02:11Z"
    },
    "builds": {
      "freeRemainingThisPeriod": 1,
      "overrunAvailable": true
    },
    "autoTopUp": {
      "enabled": true,
      "thresholdCredits": 1,
      "packCredits": 1,
      "lastError": "string"
    },
    "reservedItems": [
      {
        "action": "ken_inbox_monthly",
        "count": 1,
        "monthlyMillicredits": 1,
        "nextRenewalAt": "2026-09-23T15:02:11Z"
      }
    ],
    "pendingCreditPurchases": [
      {
        "credits": 1,
        "amountUsd": 0.5,
        "kind": "auto_top_up",
        "startedAt": "2026-09-23T15:02:11Z"
      }
    ],
    "unpaidRenewals": [
      {
        "resourceType": "inbox",
        "count": 1,
        "unpaidSince": "2026-09-23T15:02:11Z",
        "deleteAfter": "2026-09-23T15:02:11Z"
      }
    ],
    "launchOffer": {
      "startsAt": "2026-09-23T15:02:11Z",
      "endsAt": "2026-09-23T15:02:11Z",
      "used": 1,
      "limit": 1,
      "stoppedAt": "2026-09-23T15:02:11Z",
      "stoppedReason": "string"
    },
    "smtpSending": {
      "millicreditsPerEmail": 1,
      "inboxesPerDomain": 1,
      "startDailyLimit": 1,
      "dailyStep": 1,
      "maxDailyLimit": 1,
      "paused": true
    },
    "aiLimit": {
      "percentUsed": 1,
      "state": "string"
    }
  }
}
```

## Types

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

### CreditBonusPromotion

A running credit promotion: `monthlyCredits` bonus credits each billing month that starts before `endsAt`, on top of the plan's included credits.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | The offer code in uppercase, such as `EWOR`. |
| `monthlyCredits` | integer (int32) | no | The whole bonus credits the promotion grants each billing month. |
| `endsAt` | string (date-time) | no | When the promotion ends, in UTC. The end is exclusive: a billing month that starts at or after it gets no bonus credits. |

### CreditSends

Included sends in the current billing month.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `includedPerPeriod` | integer (int32) | no | Sends included each billing month. Omitted when unlimited. |
| `usedThisPeriod` | integer (int32) | no | Sends used this billing month. |
| `periodStart` | string (date-time) | no | When the current billing month started, in UTC. |
| `periodEnd` | string (date-time) | no | When the current billing month ends, in UTC. |

### CreditBuilds

Free campaign builds this billing month.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `freeRemainingThisPeriod` | integer (int32) | no | Free campaign builds left this billing month. A paid plan gets one a month. |
| `overrunAvailable` | boolean | no | Whether a build that runs out of credits can still finish, once a billing month. |

### CreditAutoTopUp

An opt-in rule that buys a credit pack when available credits drop below a threshold.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no | Whether the rule is on. |
| `thresholdCredits` | integer (int32) | no | Kenso buys a pack when available credits drop below this many whole credits. |
| `packCredits` | integer (int32) | no | Credits each top-up buys, a multiple of 1,000. |
| `lastError` | string | no | Why the last automatic purchase failed. Omitted when it did not fail. |

### CreditReservedItem

Active monthly items of one credit action and their monthly cost.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | no | The credit action: `ken_inbox_monthly`, `azure_domain_monthly`, `smtp_domain_monthly`, `smtp_inbox_domain_monthly`, `linkedin_account_monthly`, `imessage_line_monthly` or `facebook_account_monthly`. Expect new values. |
| `count` | integer (int32) | no | How many active items use this action. |
| `monthlyMillicredits` | integer (int64) | no | Their monthly cost, in millicredits. |
| `nextRenewalAt` | string (date-time) | no | When the next of them renews, in UTC: the earliest date one of them is paid through. Earlier than now while a charge for one of them is unpaid and Kenso retries it (`unpaidRenewals`). Omitted while their first charge is still pending. |

### CreditPendingPurchase

A credit purchase whose payment is still processing.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credits` | integer (int32) | no | Credits Kenso adds once the payment clears. |
| `amountUsd` | number (double) | no | What the purchase charges, in US dollars. |
| `kind` | string | no | What was bought: `auto_top_up` or `pack`. Expect new values. |
| `startedAt` | string (date-time) | no | When the payment started, in UTC. |

### CreditUnpaidRenewal

Monthly items whose renewal went unpaid at the same time. Kenso retries every hour, so buying credits pays it, and deletes items still unpaid at `deleteAfter`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resourceType` | string | no | The kind of item: `inbox`, `domain`, `linkedin_account` or `imessage_line`. Expect new values. |
| `count` | integer (int32) | no | How many items of this kind went unpaid. |
| `unpaidSince` | string (date-time) | no | When the renewal charge first failed for lack of credits, in UTC. |
| `deleteAfter` | string (date-time) | no | When Kenso may delete the items if still unpaid, usually 14 days after `unpaidSince`. |

### CreditLaunchOffer

The launch offer's window and fair use.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `startsAt` | string (date-time) | no | When the offer starts, in UTC. |
| `endsAt` | string (date-time) | no | When the offer ends, in UTC, exclusive: the last free day is the UTC day before. |
| `used` | integer (int32) | no | Lookups the offer counted in the window, found or not. |
| `limit` | integer (int32) | no | The fair use limit: free lookups for the whole window. |
| `stoppedAt` | string (date-time) | no | When the workspace reached the limit and the offer stopped for it. Omitted while the offer runs. |
| `stoppedReason` | string | no | Why the offer stopped for this workspace: `fair_use`. Omitted while the offer runs. |

### CreditSmtpSending

SMTP inboxes billed per campaign email. Warmup, seed tests, test sends and replies are free.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `millicreditsPerEmail` | integer (int64) | no | Millicredits one campaign email from an SMTP inbox costs: 250 is 0.25 credits, $5 per 1,000 emails. |
| `inboxesPerDomain` | integer (int32) | no | Inboxes on one SMTP domain. |
| `startDailyLimit` | integer (int32) | no | Emails a day a new SMTP inbox starts at. |
| `dailyStep` | integer (int32) | no | Emails a day it gains on each day it sends. |
| `maxDailyLimit` | integer (int32) | no | Emails a day it reaches. |
| `paused` | boolean | no | True when the workspace has an SMTP domain billed per email and the credits it bought cannot pay for one email: campaign sends from those inboxes wait until credits are bought. The credits a plan includes and bonus or free credits do not pay for SMTP emails. Other inboxes keep sending. |

### CreditAiLimit

The AI limit as a percent and state.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `percentUsed` | integer (int32) | no | Percent of the AI limit used, 0-100: this month's, or the one-time allowance on Kenso Lifetime. |
| `state` | string | no | `ok`, `warning` (from 80%) or `reached`. |

All resources: [/docs.md](/docs.md).
