Credits
Your credit balance.
Balance, included and purchased credits, debt, the monthly infra reservation and what is available for data and AI work, plus included sends, free builds and the auto top-up rule. A white-label child sees its master's pooled balance. Read only. Any member of the workspace; without the billing feature the response omits the billing details (includedMillicredits, purchasedMillicredits, debtMillicredits, reservedMonthlyMillicredits, includedExpiresAt, grandfatheredUntil, autoTopUp, reservedItems, pendingCreditPurchases, unpaidRenewals) and keeps the balance, what is available, exempt, exhaustedAt, creditState, the monthly included credits, sends and builds.
Parameters
Name
In
Type
Required
Description
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise
400 workspace_required).Response 200
data is a CreditBalanceModel.
Field
Type
Description
object
string
Always
credit_balance.balanceMillicredits
integer (int64)
Open grants minus debt.
includedMillicredits
integer (int64)
Remaining plan-included credits (they expire). Billing permission only.
purchasedMillicredits
integer (int64)
Remaining purchased, granted and other non-expiring credits. Billing permission only.
bonusMillicredits
integer (int64)
Remaining Bonus credits: a credit promotion's monthly credits (the EWOR offer). Part of the balance, not of
purchasedMillicredits. They are spent before the included credits, expire at the end of their billing month and cannot pay for Kenso inboxes or domains. 0 when none.bonusExpiresAt
string (date-time)
When the earliest remaining Bonus credits expire. Omitted when none are left.
bonusPromotion
CreditBonusPromotionModel
A live credit promotion:
monthlyCredits Bonus credits each billing month that starts before endsAt, on top of the plan's included credits.debtMillicredits
integer (int64)
Post-paid usage no grant has covered yet. The next grant repays it first. Billing permission only.
reservedMonthlyMillicredits
integer (int64)
Monthly cost of the active Kenso inboxes, domains and LinkedIn accounts, held back for infra. Billing permission only.
availableMillicredits
integer (int64)
What data and AI work may spend: balance minus the monthly infra reservation.
inboxDomainEligibleMillicredits
integer (int64)
What can pay for Kenso inboxes and domains: 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.
includedExpiresAt
string (date-time)
When the earliest remaining included credits expire. Omitted when none are left. Billing permission only.
monthlyIncludedCredits
integer (int32)
Credits the plan grants each billing month.
usdPerCredit
string
Price of one credit in USD, as a decimal string:
"0.02".exempt
boolean
True when the workspace is never charged for credits (charges are recorded, not debited).
creditState
string
healthy, low (under 500 credits available) or out (data and AI work cannot start: nothing available, or a white-label child cap is used up; sending and warmup keep running). Exempt workspaces are 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 a legacy plan keeps its grandfathered allowance. Omitted when not grandfathered. Billing permission only.
sends
CreditSendsModel
builds
CreditBuildsModel
autoTopUp
CreditAutoTopUpModel
Opt-in rule that buys a credit pack when available credits drop below a threshold.
reservedItems
array of CreditReservedItemModel
Active monthly infra items by action, in action order. Empty when there are none. Billing permission only.
pendingCreditPurchases
array of CreditPendingPurchaseModel
Credit packs and auto top-ups paid by bank debit whose payment is still processing, oldest first. Their credits are not in the balance yet; they are added when the payment clears. Empty when there are none. Billing permission only.
unpaidRenewals
array of CreditUnpaidRenewalModel
Kenso inboxes, domains and LinkedIn accounts whose monthly renewal could not be paid in credits, by resource type and the time they went unpaid, oldest first. Empty when every renewal is paid. Billing permission only.
launchOffer
CreditLaunchOfferModel
Launch offer window and its fair use count.
Request
curl -X GET "https://api.ken.so/v1/credits" \ -H "Authorization: Bearer $KEN_API_KEY" \ -H "Ken-Version: 2026-11-02" \ -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
"success": true,
"data": {
"object": "string",
"balanceMillicredits": 1,
"includedMillicredits": 1,
"purchasedMillicredits": 1,
"bonusMillicredits": 1,
"bonusExpiresAt": "2026-09-23T15:02:11Z",
"bonusPromotion": {
"code": "string",
"monthlyCredits": 1,
"endsAt": "2026-09-23T15:02:11Z"
},
"debtMillicredits": 1,
"reservedMonthlyMillicredits": 1,
"availableMillicredits": 1,
"inboxDomainEligibleMillicredits": 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": "string",
"count": 1,
"monthlyMillicredits": 1
}
],
"pendingCreditPurchases": [
{
"credits": 1,
"amountUsd": 0.5,
"kind": "string",
"startedAt": "2026-09-23T15:02:11Z"
}
],
"unpaidRenewals": [
{
"resourceType": "string",
"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"
}
}
}