> 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-spend/openapi.json](/docs/api/credit-spend/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Credit spend

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

What the workspace spent per category in a period.

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

- `GET /v1/credits/spend` - Get credit spend by category (`credit-spend.get`): [/docs/api/credit-spend/get.md](/docs/api/credit-spend/get.md)

## Get credit spend by category

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

| Permission | Rate limit |
| --- | --- |
| The `billing` permission | 12,000 requests a minute per API key |

Returns the credits the workspace spent in a period, split into five categories: `infrastructure`,
`ai`, `data`, `sending` and `calling`. Each category has its net millicredits, the same
amount in US cents at $0.02 a credit, and its number of ledger lines.

Set `period` to `billing_month`, `last_30_days` or `all_time`. The default is
`billing_month`, the current billing month. On the Free plan it covers every day since signup, and the
response reports `period` as `since_signup`.

Spend is net of refunds and write-offs. Like the ledger, a parent or standalone workspace includes its
white-label client workspaces.

The same spend is also split per kind of work (`actions`, largest first, each with its `title`) and per
campaign (`campaigns`: the 50 largest, plus one row with `campaignId` null for the work tied to no
campaign; `campaignsTruncated` is true when more campaigns had spend). A campaign name is shown only for a
campaign in the workspace that spent on it.

Errors:

- `400 validation_failed`: `period` is not `billing_month`, `last_30_days` or
`all_time`.

Requires the `billing` permission.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `period` | query | string | no | The period to report: `billing_month` (the default), `last_30_days` or `all_time`. |
| `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 `CreditSpend`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `credit_spend`. |
| `period` | string | The period reported: `billing_month`, `last_30_days`, `all_time`, or `since_signup` when a workspace on the Free plan asks for `billing_month`. |
| `from` | string (date-time) | The start of the period, inclusive, in UTC. Omitted for `all_time`. |
| `to` | string (date-time) | The end of the period, exclusive, in UTC: the end of the billing month, else now. |
| `totalMillicredits` | integer (int64) | All categories' millicredits added up. |
| `totalAmount` | Money | The total in US cents, at $0.02 a credit. |
| `categories` | array of CreditSpendCategory | Always all five categories, in this order: `infrastructure`, `ai`, `data`, `sending` and `calling`. |
| `addedExpiredLineCount` | integer (int32) | Grant, expiry and manual adjustment lines in the period. |
| `actions` | array of CreditSpendAction | Spend per kind of work: one row per credit action with a line in the period, largest first. A refund or write-off counts against its charge's action. Grants and expiries are left out. |
| `campaigns` | array of CreditSpendCampaign | Spend per campaign, largest first. The work tied to no campaign is one row with `campaignId` null. At most 50 campaigns, plus that row. |
| `campaignsTruncated` | boolean | True when more than 50 campaigns had spend: the smallest are left out of `campaigns`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/credits/spend" \
  -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",
    "period": "billing_month",
    "from": "2026-09-23T15:02:11Z",
    "to": "2026-09-23T15:02:11Z",
    "totalMillicredits": 1,
    "totalAmount": {
      "amount": 1,
      "currency": "usd"
    },
    "categories": [
      {
        "category": "infrastructure",
        "millicredits": 1,
        "amount": {
          "amount": 1,
          "currency": "usd"
        },
        "lineCount": 1
      }
    ],
    "addedExpiredLineCount": 1,
    "actions": [
      {
        "action": "email_found",
        "title": "string",
        "category": "infrastructure",
        "millicredits": 1,
        "amount": {
          "amount": 1,
          "currency": "usd"
        },
        "lineCount": 1
      }
    ],
    "campaigns": [
      {
        "campaignId": 812,
        "campaignName": "string",
        "millicredits": 1,
        "amount": {
          "amount": 1,
          "currency": "usd"
        },
        "lineCount": 1
      }
    ],
    "campaignsTruncated": true
  }
}
```

## Types

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

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

### CreditSpendCategory

The spend of one category in the period.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | no | The category: `infrastructure`, `ai`, `data`, `sending` or `calling`. |
| `millicredits` | integer (int64) | no | The net millicredits charged: charges minus refunds and write-offs. Negative when a refund lands in a later period than its charge. |
| `amount` | Money | no | The same amount in US cents, at $0.02 a credit. |
| `lineCount` | integer (int32) | no | Ledger lines in the category, including lines Kenso did not charge. |

### CreditSpendAction

The spend of one kind of work in the period.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | no | The credit action, such as `email_found`. |
| `title` | string | no | The plain name of the work, the same as a ledger line's `title`, such as `Valid email found`. |
| `category` | string | no | The spend category the action is in: `infrastructure`, `ai`, `data`, `sending` or `calling`. |
| `millicredits` | integer (int64) | no | The net millicredits charged: charges minus refunds and write-offs. |
| `amount` | Money | no | The same amount in US cents, at $0.02 a credit. |
| `lineCount` | integer (int32) | no | Ledger lines of the action, including lines Kenso did not charge. |

### CreditSpendCampaign

The spend of one campaign in the period, or of the work tied to no campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignId` | integer (int64) | no | The campaign. Null for the work tied to no campaign. |
| `campaignName` | string | no | The campaign's name. Null when there is no campaign or it was deleted. |
| `millicredits` | integer (int64) | no | The net millicredits charged: charges minus refunds and write-offs. |
| `amount` | Money | no | The same amount in US cents, at $0.02 a credit. |
| `lineCount` | integer (int32) | no | Ledger lines of the campaign, including lines Kenso did not charge. |

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