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

# Credit ledger

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

Every credit added and spent.

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

- `GET /v1/credits/ledger` - List credit ledger lines (`credit-ledger.list`): [/docs/api/credit-ledger/list.md](/docs/api/credit-ledger/list.md)

## List credit ledger lines

`GET /v1/credits/ledger` - operationId `credit-ledger.list`

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

Lists the lines on the workspace's credit account, newest first: charges, refunds, grants, expiries and
adjustments. A parent or standalone workspace also sees the lines of its white-label client workspaces, and
`workspaceId` on each line names the workspace that caused it. A white-label client workspace sees only its
own lines.

Optional filters:

- `from` and `to`: instants in UTC, both inclusive.
- `action`: credit actions, comma-separated, such as `email_found,web_scrape`. A line matches any.
- `campaignId`: the lines of one campaign.
- `category`: spend categories, comma-separated. A line matches any of them: `infrastructure`,
`ai`, `data`, `sending`, `calling` or `added_expired`. A refund or write-off belongs
to its charge's category.
- `trigger`: what started the work, comma-separated: `person`, `ken`, `workflow`,
`campaign_schedule` or `renewal`. A line matches any.
- `actorUserId`: the lines a member started.
- `contactId`, `accountId`: the lines for one contact or account.
- `listId`, `workflowId`: the lines for one list or workflow, older workflow lines included.
- `chatId`: the lines of one Ken chat, its Ken run included. An unknown chat gives an empty page.
- `runId`: every line of one run (a line's `run.id`), 1 to 100 characters.
- `q`: text, 2 to 200 characters, case-insensitive. Matches a line's description as shown, title, web URL,
or the name of its contact, account, list, workflow, Ken chat or campaign.

Filters combine with AND. `limit` is from 1 to 200, and the default is 50.

Errors:

- `400 validation_failed`: a filter, `limit` or `cursor` is invalid, or `from` is after
`to`. `error.details` names the field.

Requires the `billing` permission.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | The page size, from 1 to 200. The default is 50. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Omit it for the first page. |
| `from` | query | string (date-time) | no | Only lines created at or after this instant, in UTC. |
| `to` | query | string (date-time) | no | Only lines created at or before this instant, in UTC. |
| `action` | query | string | no | Only lines of these credit actions, comma-separated, such as `email_found,web_scrape`. A line matches any of them. |
| `campaignId` | query | integer (int64) | no | Only lines of this campaign. |
| `category` | query | string | no | Only lines in these spend categories, comma-separated: `infrastructure`, `ai`, `data`, `sending`, `calling` or `added_expired`. A refund or write-off belongs to its charge's category. |
| `trigger` | query | string | no | Only lines started this way, comma-separated: `person`, `ken`, `workflow`, `campaign_schedule` or `renewal`. A line matches any of them. |
| `actorUserId` | query | integer (int64) | no | Only lines this member started. |
| `contactId` | query | integer (int64) | no | Only lines for this contact. |
| `accountId` | query | integer (int64) | no | Only lines for this account. |
| `listId` | query | integer (int64) | no | Only lines for this list. |
| `workflowId` | query | integer (int64) | no | Only lines of this workflow, older lines that named it only in their description included. |
| `chatId` | query | integer (int64) | no | Only lines of this Ken chat: the chat itself and its Ken run. |
| `runId` | query | string | no | Only the lines of this run (a line's `run.id`), 1 to 100 characters. |
| `q` | query | string | no | Text search, 2 to 200 characters, case-insensitive: a line's description as shown, title, web URL, or the name of its contact, account, list, workflow, Ken chat or campaign. |
| `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 list of `CreditLedgerEntry`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The line id. |
| `createdAt` | string (date-time) | When Kenso wrote the line, in UTC. |
| `action` | string | The credit action, such as `email_found`, `campaign_build`, `grant` or `refund`. |
| `units` | integer (int32) | Units the line is for, such as contacts or sends. Omitted for AI work priced by what it did and for bookkeeping lines. |
| `millicredits` | integer (int64) | The signed amount in millicredits. |
| `reason` | string | Why the line exists: `charge`, `release`, `settle`, `add_on`, `rebaseline`, `write_off`, `expire`, `launch_offer` for a charge the launch offer waived, `email_pool_hit` for free emails from Kenso's shared pool, counted in `units`, or `own_key` for work that ran on the workspace's own provider key, counted in `units`. The last three cost nothing. |
| `campaignId` | integer (int64) | The campaign the line is for. Omitted for work outside a campaign. |
| `workspaceId` | integer (int64) | The workspace that caused the line, possibly a white-label client workspace. |
| `description` | string | A short description. Omitted when none. |
| `shadow` | boolean | True when the workspace is exempt: Kenso recorded the cost but did not charge it. |
| `category` | string | The spend category: `infrastructure`, `ai`, `data`, `sending`, `calling`, or `added_expired` for grants, expiries and manual adjustments. A refund or write-off is in its charge's category. Expect new values. |
| `title` | string | The plain name of the work, such as `Web page read`, `Valid email found` or `Campaign built by Ken`. |
| `subjectType` | string | The object the line was for: `contact`, `account`, `list`, `workflow`, `chat` or `campaign`. Expect new values. |
| `subjectId` | integer (int64) | The id of that object in the line's workspace. |
| `subjectName` | string | The object's name: a contact's full name (else email), or the account, list, workflow, chat or campaign name. Omitted when the object is gone. |
| `webUrl` | string | The page a web read fetched. |
| `webSite` | string | The website of `webUrl`: its host in lower case and in its own letters, without a leading `www.`. |
| `webPage` | string | The page of `webUrl`: its path and query, unescaped, `/` for the home page. |
| `trigger` | string | What started the work: `person` (see `actorUserId`), `ken`, `workflow` (see `workflowId`), `campaign_schedule` or `renewal`. Expect new values. |
| `actorUserId` | integer (int64) | The person who started the work. |
| `actorName` | string | That person's name, else their email. `Ken support` when a Kenso staff member caused the line. |
| `workflowId` | integer (int64) | The workflow whose run did the work. |
| `workflowName` | string | That workflow's name. |
| `listId` | integer (int64) | The list the work was for. |
| `listName` | string | That list's name. |
| `campaignName` | string | The name of the campaign in `campaignId`. |
| `chatId` | integer (int64) | The Ken chat the line was for. Support, Studio and Slack chats are never named here. |
| `chatTitle` | string | That chat's title. |
| `chatMessageCount` | integer (int32) | Messages in that chat now. |
| `run` | CreditLedgerRun | The run the line belongs to, with the run's total, so a client can fold its lines into one row. |
| `paidFrom` | string | Which credits paid a charge: `paid` (plan and purchased credits), `free` (free credits) or `mixed`. Omitted for anything but a charged line. |
| `creditGrantId` | integer (int64) | The grant a grant, expiry or refund line added to or took from. |
| `creditGrantKind` | string | Whether that grant is `paid` or `free` credits. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/credits/ledger?limit=50" \
  -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": [
    {
      "id": 812,
      "createdAt": "2026-09-23T15:02:11Z",
      "action": "email_found",
      "units": 1,
      "millicredits": 1,
      "reason": "string",
      "campaignId": 812,
      "workspaceId": 812,
      "description": "string",
      "shadow": true,
      "category": "infrastructure",
      "title": "string",
      "subjectType": "contact",
      "subjectId": 812,
      "subjectName": "string",
      "webUrl": "https://example.com",
      "webSite": "https://example.com",
      "webPage": "string",
      "trigger": "string",
      "actorUserId": 812,
      "actorName": "string",
      "workflowId": 812,
      "workflowName": "string",
      "listId": 812,
      "listName": "string",
      "campaignName": "string",
      "chatId": 812,
      "chatTitle": "string",
      "chatMessageCount": 1,
      "run": {
        "id": "string",
        "kind": "campaign_build",
        "title": "string",
        "lineCount": 1,
        "millicredits": 1,
        "startedAt": "2026-09-23T15:02:11Z"
      },
      "paidFrom": "string",
      "creditGrantId": 812,
      "creditGrantKind": "string"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

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

### CreditLedgerRun

The run a ledger line belongs to.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The run id. For AI work it is the id Kenso reports model usage under. |
| `kind` | string | no | The kind of run, such as `campaign_build`, `account_research`, `ken_chat`, `reply_assist` or `workflow_run`. Expect new values. |
| `title` | string | no | The plain name of the run, such as `Campaign built by Ken`. |
| `lineCount` | integer (int32) | no | The run's lines this workspace can see, on every page. |
| `millicredits` | integer (int64) | no | Those lines' signed millicredits added up; lines Kenso did not charge count 0. |
| `startedAt` | string (date-time) | no | When the run's first line was written, in UTC. |

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