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

# Credit estimates

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

Estimate what a campaign, a build, infrastructure or new accounts will cost in credits. Nothing is charged.

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/credit-estimates/openapi.json](/docs/api/credit-estimates/openapi.json).

- `POST /v1/credits/estimates` - Estimate the credits a job needs (`credit-estimates.create`): [/docs/api/credit-estimates/create.md](/docs/api/credit-estimates/create.md)

## Estimate the credits a job needs

`POST /v1/credits/estimates` - operationId `credit-estimates.create`

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

Estimates the credits a job needs before you start it, and their price in US cents (`totalAmount`). Kenso only
computes the estimate: nothing is charged or reserved.

Set `kind` and send only the fields of that kind:

- `campaign`: `targetLeads` (from 1 to 1,000,000), `sequenceSteps` (from 1 to 50) and
`personalization`. With `campaignId`, missing values come from that campaign: its contact limit, step
count and personalization setting. Otherwise steps default to 3 and personalization to true.
Without `targetLeads`, the campaign's contact limit below 1,000,000 is priced, else its lead count;
`targetLeads` is required when the campaign has neither. Instead of
`personalization`, send `depth` to price every lead at a depth on the rate card: `bulk`,
`personalized` or `multichannel`. The response names the `depth` and `targetLeads` it
priced.
With a `campaignId`, leads already qualified, already written or already holding an email are quoted
free (stages with note `already_done_free`), and `leadsWithCopy` says how many leads have copy. Send
`run` `rewrite` to quote writing copy again for every lead. Send `run` `write_new` to quote
writing copy only for the leads that have none. A campaign whose own workflow is live
also gets that workflow's stages (each with a `stepId`) and one line with action `workflow`.
- `build`: one typical campaign build. It costs 0 while the workspace's free monthly build is left.
- `infra`: `items`, from 1 to 50 purchases of inboxes, domains, LinkedIn accounts, WhatsApp accounts or
iMessage lines. A monthly item counts its first month up front.
- `accounts`: `accountCount`, from 1 to 1,000. Each account costs an estimated 12 credits of
research, metered per run, plus about 6 buying committee emails, charged only when found. Where the plan's AI
limit applies, research costs 0 credits and counts toward that limit instead.
- `leads`: `leadCount`, from 1 to 1,000,000. Before the workspace has measured rates, a lead costs
1.45 credits: about 3 rows qualified, 1 email found and 1 personalization. Once rates are measured the price
follows them, so use the response's total and `quote`, not this figure. Send `leadsWithEmail` (from 0
to `leadCount`) when some leads already hold an email: they need no find.
- `committee_mapping`: `accountCount`, from 1 to 1,000. Mapping the buying committee for that many
accounts: one mapping run an account, metered per run, plus the emails the run finds, up to 6 an account, charged
only when found. Where the plan's AI limit applies, the run costs 0 credits and counts toward that limit instead.
- `account_research`: `accountCount`, from 1 to 1,000. Refreshing research on that many accounts: one
research run an account, metered per run. Where the plan's AI limit applies, the run costs 0 credits and counts
toward that limit instead.
- `places`: `pages`, from 0 to 1,000 (a search page holds up to 200 places), and `opens` of a
place's details, reviews or photos, from 0 to 100,000. Send at least one of them above 0. Under new pricing each
page and each open is one request, at 5 credits per 1,000 requests, with no free opens. Otherwise a page costs 1
credit, and a workspace gets 500 free opens each UTC day, then 0.1 credits an open; the estimate assumes none of
today's free opens is used.
- `capacity`: what the plan covers in a month. Send `leadsPerMonth` (from 1 to 1,000,000) and
`depth` (default `personalized`) to learn whether the plan's monthly credits and its AI limit cover
that goal; `capacity.extraMillicredits` and `capacity.extraUsdCents` say what is missing. Omit
`leadsPerMonth` to get `capacity.coveredLeadsPerMonth`, the volume the plan covers at that depth, and
`capacity.limitedBy`, what caps it. The comparison uses the plan's monthly credits, not the balance. When the
plan's AI limit pays for part of the work and cannot be read, or is 0, the answer carries neither `quote`
nor `capacity`.

`sufficient` says whether the workspace can cover the estimate now. Free and bonus credits cannot pay for
Kenso inboxes, domains or iMessage lines, unless the workspace is exempt or Kenso staff allowed its free credits
for them.

Errors:

- `400 validation_failed`: `kind` is missing or unknown, a value is out of range, or a field
belongs to another kind.
- `404 not_found`: `campaignId` is not a campaign in this workspace.

Open to any workspace member.

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

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

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | Required. The job to estimate: `campaign`, `build`, `infra`, `accounts`, `leads`, `places`, `committee_mapping`, `account_research` or `capacity`. |
| `campaignId` | integer (int64) | no | Campaign estimates only: a campaign to read the contact limit, step count and personalization setting from. |
| `targetLeads` | integer (int32) | no | Campaign estimates only: the contacts the campaign should finish with, from 1 to 1,000,000. Without it a `campaignId` is priced on its contact limit below 1,000,000, else on its lead count; required when the campaign has neither. |
| `sequenceSteps` | integer (int32) | no | Campaign estimates only: the number of sequence steps, from 1 to 50. Defaults to the campaign's step count, else 3. |
| `personalization` | boolean | no | Campaign estimates only: whether Kenso personalizes each contact. Defaults to the campaign's setting, else true. |
| `depth` | string | no | Campaign and capacity estimates: how deep Kenso works each lead, `bulk`, `personalized` or `multichannel`. Send it or `personalization`, not both. Defaults to `personalized` when personalization is on, else `bulk`. A capacity estimate defaults to `personalized`. |
| `run` | string | no | Campaign estimates only: which run to quote. `campaign` (the default) is the whole campaign, with leads already qualified, written or holding an email quoted free. `rewrite` is writing copy again for every lead that reaches writing, and needs `campaignId`. `write_new` is writing copy only for leads that have none, and needs `campaignId` too. |
| `items` | array of CreditEstimateInfraItemRequest | no | Infra estimates only: from 1 to 50 purchases. |
| `accountCount` | integer (int32) | no | Accounts, committee mapping and account research estimates: the accounts to add, map or refresh, from 1 to 1,000. |
| `leadCount` | integer (int32) | no | Leads estimates only: the leads to import, from 1 to 1,000,000. |
| `leadsWithEmail` | integer (int32) | no | Leads estimates only: how many of the leads already hold an email, from 0 to `leadCount`. They need no email found. Omit it when none do. |
| `pages` | integer (int32) | no | Places estimates only: search pages of up to 200 places each, from 0 to 1,000. Send `pages` or `opens` above 0. |
| `opens` | integer (int32) | no | Places estimates only: opens of a place's details, reviews or photos, from 0 to 100,000. Under new pricing every open is charged; otherwise the first 500 a workspace makes each UTC day are free. |
| `leadsPerMonth` | integer (int32) | no | Capacity estimates only: the goal, leads a month, from 1 to 1,000,000. Omit it to ask how many leads a month the plan covers. |

### Response 200

`data` is a `CreditEstimate`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `credit_estimate`. |
| `totalMillicredits` | integer (int64) | The millicredits the job needs now, counting the first month of monthly items. |
| `monthlyRecurringMillicredits` | integer (int64) | What an infra purchase adds to `reservedMonthlyMillicredits`. 0 for other kinds. |
| `lines` | array of CreditEstimateLine | The estimate's lines, one per credit action. |
| `availableMillicredits` | integer (int64) | What the estimate is measured against: the whole balance for `infra`, else available credits. |
| `sufficient` | boolean | Whether the workspace can cover the estimate now. Always true for an exempt workspace. |
| `freeBuild` | boolean | Build estimates only: whether the free monthly build covers it. |
| `inboxDomainEligibleMillicredits` | integer (int64) | Infra estimates only: what can pay the inbox, domain and iMessage line items, the balance minus free and bonus credits, or the whole balance when the workspace is exempt or Kenso staff allowed its free credits for them. `sufficient` is false when those items cost more, even when `availableMillicredits` covers the total. |
| `totalAmount` | Money | `totalMillicredits` in US cents, at `usdPerCredit` on the rate card. |
| `depth` | string | Campaign and capacity estimates only: the depth priced, `bulk`, `personalized` or `multichannel`, as sent or derived from the campaign's personalization. Omitted for other kinds. |
| `targetLeads` | integer (int32) | Campaign estimates only: the leads priced, as sent or read from the campaign's contact limit or lead count. Omitted for other kinds. |
| `leadsNeedingEmailFind` | integer (int32) | Campaign estimates only: the email finds the estimate charges for, the units of its `email_found` line. Leads whose email find is already settled in the campaign are quoted none. Omitted for other kinds. |
| `leadsWithCopy` | integer (int32) | Campaign estimates with a `campaignId`: how many of the campaign's leads already have copy. A `rewrite` run writes them again. Omitted for other kinds and without a campaign. |
| `quote` | CostQuote | The cost quote behind this estimate (range, stages, share of the AI limit). Null until this estimate is quoted. |
| `capacity` | CreditCapacity | Capacity estimates only: what the plan covers at the depth priced. Omitted for other kinds, and when the estimate carries no `quote`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/credits/estimates" \
  -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 '{
  "kind": "campaign",
  "campaignId": 812,
  "targetLeads": 1,
  "sequenceSteps": 1,
  "personalization": true,
  "depth": "personalized",
  "run": "campaign",
  "items": [
    {
      "action": "ken_inbox_monthly",
      "quantity": 1,
      "registrarPriceUsd": 0.5,
      "renewalPriceUsd": 0.5
    }
  ],
  "accountCount": 1,
  "leadCount": 1,
  "leadsWithEmail": 1,
  "pages": 1,
  "opens": 1,
  "leadsPerMonth": 1
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "object": "string",
    "totalMillicredits": 1,
    "monthlyRecurringMillicredits": 1,
    "lines": [
      {
        "action": "email_found",
        "units": 1,
        "millicredits": 1,
        "description": "string"
      }
    ],
    "availableMillicredits": 1,
    "sufficient": true,
    "freeBuild": true,
    "inboxDomainEligibleMillicredits": 1,
    "totalAmount": {
      "amount": 1,
      "currency": "usd"
    },
    "depth": "string",
    "targetLeads": 1,
    "leadsNeedingEmailFind": 1,
    "leadsWithCopy": 1,
    "quote": {
      "credits": {
        "expectedMillicredits": 1,
        "lowMillicredits": 1,
        "highMillicredits": 1,
        "maxMillicredits": 1,
        "expectedUsdCents": 1,
        "lowUsdCents": 1,
        "highUsdCents": 1
      },
      "aiLimit": {
        "applies": true,
        "expectedPercent": 0.5,
        "lowPercent": 0.5,
        "highPercent": 0.5,
        "usedPercentNow": 0.5,
        "fits": true
      },
      "balance": {
        "availableMillicredits": 1,
        "afterMillicredits": 1,
        "sufficient": true,
        "shortMillicredits": 1,
        "shortAtHighMillicredits": 1
      },
      "basis": {
        "source": "string",
        "windowDays": 1,
        "sampleSize": 1
      },
      "per": {
        "unit": "string",
        "count": 1
      },
      "stages": [
        {
          "key": "string",
          "label": "string",
          "unitsIn": 1,
          "unitsOut": 1,
          "paidBy": "string",
          "expectedMillicredits": 1,
          "aiLimitPercent": 0.5,
          "note": "string",
          "stepId": "string"
        }
      ],
      "savings": [
        {
          "code": "string",
          "stepId": "string",
          "title": "string",
          "detail": "string",
          "savesMillicredits": 1,
          "savesAiLimitPercent": 0.5,
          "per": 1,
          "fixDefinition": null
        }
      ]
    },
    "capacity": {
      "depth": "bulk",
      "leadsPerMonth": 1,
      "quotedLeads": 1,
      "planMonthlyMillicredits": 1,
      "covered": true,
      "extraMillicredits": 1,
      "extraUsdCents": 1,
      "aiLimitPercent": 0.5,
      "coveredLeadsPerMonth": 1,
      "limitedBy": "credits",
      "exempt": true
    }
  }
}
```

## Types

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

### CreditEstimateInfraItemRequest

One purchase in an infra estimate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | yes | Required. What to buy: `ken_inbox_monthly`, `prewarmed_inbox`, `azure_domain_monthly`, `smtp_domain_monthly`, `smtp_inbox_domain_monthly`, `linkedin_account_monthly`, `imessage_line_monthly`, `whatsapp_account_monthly` or `domain_registration`. |
| `quantity` | integer (int32) | no | How many to buy, from 1 to 1,000. The default is 1. |
| `registrarPriceUsd` | number (double) | no | The registrar's price in US dollars, above 0 and at most 1,000. Required for `domain_registration` and refused for every other action. |
| `renewalPriceUsd` | number (double) | no | The yearly renewal price in US dollars, above 0 and at most 1,000. Only for `domain_registration`. |

### CreditEstimateLine

One line of a credit estimate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | no | The credit action, such as `email_found`; `workflow` for the one line that covers a campaign's own live workflow. |
| `units` | integer (int64) | no | Units the job needs. |
| `millicredits` | integer (int64) | no | What the line costs, in millicredits. |
| `description` | string | no | What the line covers, in plain words. |

### Money

An amount of money.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | integer (int64) | no | The amount in the currency's smallest unit, such as cents for `usd`: 1250 is 12.50 dollars. |
| `currency` | string | no | The currency, as a lowercase three-letter ISO 4217 code such as `usd`. |

### CostQuote

The cost quote an estimate response carries as `quote`: the credits range, the share of the AI limit, the balance, what the numbers are based on, and the stages and savings behind them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credits` | CostQuoteCredits | no | Credits: expected, the low and high that aim to contain 80% of runs, and the most the work is priced at. That most is a cap only where the action caps its charge: a run charged by what it costs (account research, a committee mapping run) is priced at its range's high and nothing caps it, while committee mapping's emails stop at 6 an account. |
| `aiLimit` | CostQuoteAiLimit | no | The work's share of the workspace's AI limit, in percent. |
| `balance` | CostQuoteBalance | no | The available balance against the expected cost, and what would be missing at the high end. |
| `basis` | CostQuoteBasis | no | Where the rates came from, over how many days and samples: `workspace` (the workspace's own trailing rates), `kenso` (typical across customer workspaces), `pilot` (this campaign's or workflow's own first runs) or `preset` (no data yet). |
| `per` | CostQuotePer | no | What the quote counts (`lead`, `record`, `account`, `run` or `item`) and how many. |
| `stages` | array of CostQuoteStage | no |  |
| `savings` | array of CostQuoteSaving | no |  |

### CreditCapacity

What a plan covers in a month at one depth. Credits are the plan's monthly credits, never the balance.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `depth` | string | no | The depth priced: `bulk`, `personalized` or `multichannel`. |
| `leadsPerMonth` | integer (int32) | no | The goal as sent, leads a month. Null when the request asked what the plan covers. |
| `quotedLeads` | integer (int32) | no | The leads the `quote` and `aiLimitPercent` are for: the goal, or 1,000 when the request asked what the plan covers. Scale nothing from it: `coveredLeadsPerMonth` is already the plan's volume. |
| `planMonthlyMillicredits` | integer (int64) | no | The credits the plan includes each month, in millicredits. |
| `covered` | boolean | no | Whether the plan's monthly credits and its AI limit both cover the goal. Null without a goal. |
| `extraMillicredits` | integer (int64) | no | The credits the goal needs beyond the plan's monthly credits, in millicredits. 0 when covered or without a goal. |
| `extraUsdCents` | integer (int64) | no | `extraMillicredits` in US cents, at `usdPerCredit` on the rate card. |
| `aiLimitPercent` | number (double) | no | The share of the AI limit the `quotedLeads` use, in percent. Null where the workspace's AI work is charged in credits. |
| `coveredLeadsPerMonth` | integer (int64) | no | About how many leads a month the plan's credits and AI limit cover at this depth, at most 1,000,000. |
| `limitedBy` | string | no | What caps `coveredLeadsPerMonth`: `credits` or `ai_limit`. Null when neither caps it below 1,000,000. |
| `exempt` | boolean | no | True when the workspace's credit balance is never checked. The other fields are the plan's numbers, as for any workspace. |

### CostQuoteCredits

Credits: expected, the low and high that aim to contain 80% of runs, and the most the work is priced at. That most is a cap only where the action caps its charge: a run charged by what it costs (account research, a committee mapping run) is priced at its range's high and nothing caps it, while committee mapping's emails stop at 6 an account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expectedMillicredits` | integer (int64) | no |  |
| `lowMillicredits` | integer (int64) | no |  |
| `highMillicredits` | integer (int64) | no |  |
| `maxMillicredits` | integer (int64) | no |  |
| `expectedUsdCents` | integer (int64) | no |  |
| `lowUsdCents` | integer (int64) | no |  |
| `highUsdCents` | integer (int64) | no |  |

### CostQuoteAiLimit

The work's share of the workspace's AI limit, in percent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `applies` | boolean | no |  |
| `expectedPercent` | number (double) | no |  |
| `lowPercent` | number (double) | no |  |
| `highPercent` | number (double) | no |  |
| `usedPercentNow` | number (double) | no |  |
| `fits` | boolean | no |  |

### CostQuoteBalance

The available balance against the expected cost, and what would be missing at the high end.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `availableMillicredits` | integer (int64) | no |  |
| `afterMillicredits` | integer (int64) | no |  |
| `sufficient` | boolean | no |  |
| `shortMillicredits` | integer (int64) | no |  |
| `shortAtHighMillicredits` | integer (int64) | no |  |

### CostQuoteBasis

Where the rates came from, over how many days and samples: `workspace` (the workspace's own trailing rates), `kenso` (typical across customer workspaces), `pilot` (this campaign's or workflow's own first runs) or `preset` (no data yet).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | no |  |
| `windowDays` | integer (int32) | no |  |
| `sampleSize` | integer (int64) | no |  |

### CostQuotePer

What the quote counts (`lead`, `record`, `account`, `run` or `item`) and how many.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `unit` | string | no |  |
| `count` | integer (int64) | no |  |

### CostQuoteStage

One stage of the work: units in and out, its expected cost, and what pays for it: `credits`, `ai_limit` (the plan's AI limit), `plan` (included, unless `note` is `price_unknown`) or `dollars` (add-ons). `note` is `only_when_found` (charged only for a result), `already_done_free` (done already, not charged again), `list_below_limit` (the list yields fewer leads than its contact limit), `price_unknown` (the price depends on something the estimate does not have yet: its 0 credits are not a price and the stage is not included) or absent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no |  |
| `label` | string | no |  |
| `unitsIn` | integer (int64) | no |  |
| `unitsOut` | integer (int64) | no |  |
| `paidBy` | string | no |  |
| `expectedMillicredits` | integer (int64) | no |  |
| `aiLimitPercent` | number (double) | no |  |
| `note` | string | no |  |
| `stepId` | string | no |  |

### CostQuoteSaving

One way to spend less: what the fix saves for every `per` units, and the definition with the fix applied.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no |  |
| `stepId` | string | no |  |
| `title` | string | no |  |
| `detail` | string | no |  |
| `savesMillicredits` | integer (int64) | no |  |
| `savesAiLimitPercent` | number (double) | no |  |
| `per` | integer (int32) | no |  |
| `fixDefinition` | object | no |  |

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