# Plans & credits

The Free, Team and Enterprise plans, what spends credits, how the account wallet, top-ups and seats work, and where to track usage.

Canonical page: https://kortix.com/docs/credits

Credits are the balance of an account's wallet. Every project in the account spends from that one wallet. This page is for the people who pay for an account and the members who watch its spend.

The API and `--json` output report amounts in money. Billing and the CLI show the same amounts as credits: an API amount of `1.00` is 100 credits.

To see the balance now, run `kortix billing status`, or open the project menu → **Switch Project** → **Account settings** → **Billing** → **Plan**.

## Plans

An account is on one of three plans. See [kortix.com/pricing](https://kortix.com/pricing) for what each plan costs and grants.

| | Free | Team | Enterprise |
| --- | --- | --- | --- |
| Billed | No charge | Per seat | By contract |
| Credit grant | Every month, for the account | Every billing cycle, per seat, pooled in one wallet | By contract |
| Kortix-managed models | The platform default only | All | All |
| Buy credits and auto top-up | No | Yes | Yes |
| Projects | 1 | 200 | No limit |
| SSO, SCIM, groups and custom roles, audit log, branding | No | No | Yes |

- Every plan can use models on your own provider key or a ChatGPT subscription. See [Models](/docs/project/models).
- A managed model outside your plan returns `plan_upgrade_required`.
- An Enterprise feature outside your plan returns `402` with code `entitlement_required`. See [Sign-in, SSO & API keys](/docs/accounts/identity#enterprise-features).
- An account on an older plan sees it under its family name: Free, Team or Enterprise. It keeps the terms it bought. Some older paid plans do not meter sandbox compute.
- Creating a project over the limit returns `403` with code `project_limit_reached`. An archived project does not count.
- To move from Free to Team, select **Subscribe to Team** on **Billing → Plan**. For Enterprise, email [support@kortix.com](mailto:support@kortix.com).

A self-hosted instance runs with billing off by default (`KORTIX_BILLING_INTERNAL_ENABLED=false`). It has no credits, no plan limits and no managed models. `kortix billing status` still answers there and never blocks a run. `kortix billing transactions` returns `404` with `billing_disabled: true`. See [Self-hosting](/docs/host).

## What uses credits

| What | How Kortix meters it |
| --- | --- |
| Kortix-managed model calls | Input, output and cache tokens of each request. |
| Sandbox compute | The reserved spec (`cpu`, `memory`, `disk`) multiplied by the seconds the sandbox is active. Session sandboxes, App machines and project monitors all count. |
| Kortix-proxied tools | Each web search, image search or web scraping request that goes through Kortix. |

- Compute meters the spec the sandbox reserves, not what it uses. Set the spec in `kortix.yaml`. See [Sandboxes & previews](/docs/work/runtime#hardware-and-docker).
- One compute rate applies to every sandbox provider.
- A stopped or sleeping sandbox accrues nothing. See [Sessions](/docs/work/sessions#when-a-session-sleeps).
- A running sandbox is billed every 5 minutes and again when it stops.
- A model request on your own provider key or a ChatGPT subscription has no Kortix charge. Your provider bills you.

## Credit buckets

The wallet holds two buckets.

| Bucket | Filled by | Expires |
| --- | --- | --- |
| Expiring | The plan grant | The next grant replaces it. Unused credits do not carry over. |
| Non-expiring | Top-ups, auto top-ups, refunds and promotional grants | Never |

- Kortix spends the expiring bucket first, then the non-expiring bucket.
- Work that finished is always recorded. When it costs more than the balance, the non-expiring bucket goes below zero. The balance stays below zero until new credits cover the difference.
- A run needs a positive balance.
- `kortix billing transactions --breakdown` also shows a daily bucket. No current plan fills it.

## Top-ups and auto top-up

Only paid plans can buy credits. Top-ups go into the non-expiring bucket.

### Add credits
On **Billing → Plan**, select **Add credits**, choose an amount, and pay.
### Turn on auto top-up
In **Auto top-up**, set the amount to add and the balance that triggers it. The threshold and the amount are each at least 100 credits. The amount must be at least 100 credits above the threshold. Auto top-up needs a saved payment method. When the balance is already at or below the threshold, the first charge runs at once.

Credits follow settled payments. A card settles at once. A bank debit can take several business days. The credits arrive when it settles, and a failed debit adds nothing. While one bank-debit auto top-up is still settling, auto top-up does not start a second charge.

When an auto top-up charge fails:

1. A temporary failure is tried again on a later debit: no sooner than 5 minutes after the 1st failure, and 30 minutes after the 2nd.
2. A hard decline (for example `card_declined`, `insufficient_funds` or `expired_card`), or the 3rd failed charge in a row, turns auto top-up off.
3. Every owner gets an email with the reason. **Auto top-up** shows the date and the reason beside the switch.
4. Update the payment method in **Manage billing**, then turn auto top-up on again. This clears the failure count.

## Seats and plan changes

A seat is an accepted member of a Team account. Seats follow membership: when a member joins or leaves, the seat count changes. Billing counts at most 100 seats.

| Change | Charge | Credits |
| --- | --- | --- |
| Add a member | The seat is charged now, prorated for the rest of the cycle. | The prorated share of the seat's grant arrives when that charge is paid. |
| Remove a member | The lower count applies from the next renewal. No refund. | Credits already granted stay in the wallet. |
| Move a paid plan to a higher plan | The difference is charged now. The upgrade applies only when that payment succeeds. | The prorated share of the new grant arrives with the payment. The next renewal grants the full amount. |
| Cancel | **Cancel subscription** ends the plan at the end of the current billing period. **Reactivate subscription** undoes it until then. | The plan grant stops after the period ends. |

Manage the plan, the payment method and invoices under **Billing → Plan** and **Manage billing**. These changes need the `billing.write` permission, which only the owner role holds by default. Every member can read billing (`billing.read`). See [Accounts & access](/docs/accounts).

## Running out

When the balance reaches zero, agents pause and triggers stop starting sessions. Starting a session or sending a prompt returns `402`:

| Code | Means | Fix |
| --- | --- | --- |
| `insufficient_credits` | The wallet is empty, or the last payment failed. | Add credits, or update the payment method. On Free, subscribe to Team or wait for the next monthly grant. |
| `subscription_required` | A Team account has no active subscription. | Subscribe on **Billing → Plan**. |
| `no_account` | The account has no credit account yet. | Finish account setup, or email [support@kortix.com](mailto:support@kortix.com). |

- The `402` body also carries `billing_state`: `out_of_credits`, `payment_failed`, `no_subscription` or `no_account`.
- Kortix stops the running Apps of the account. A visitor gets `402` with code `app_account_unfunded` and an **App paused** page. See [Apps](/docs/apps).
- On a paid plan with auto top-up off, every owner gets one email per UTC day when the balance reaches zero.
- A member who cannot add credits can select **Ask an owner** in the out-of-credits notice. Every owner gets an email with the balance and a link to billing. Each member can ask once per 24 hours per account.

## Track usage

| Where | What it shows |
| --- | --- |
| **Billing → Plan** | Plan, wallet, spend this period, auto top-up |
| **Billing → Usage** | Kortix charges and the credit ledger |
| **Customize → Models → Costs** in a project | Model spend and budgets for that project. See [Models](/docs/project/models#budgets-and-costs). |

The CLI reads the same data. It cannot change billing.

```bash
kortix billing status                                   # plan, credits, seats, subscription
kortix billing transactions --summary --days 7          # credits in and out
kortix billing costs                                    # account totals and model breakdown, last 30 days
kortix billing costs --by project --since 2026-09-01T00:00:00Z
kortix billing costs --by session --csv sessions.csv    # CSV needs --by
```

`kortix billing costs` takes `--project`, `--session`, `--owner`, `--since`, `--until`, `--sort total_desc|total_asc|recent|name_asc` (`name_asc` with `--by project` only), `--limit` and `--offset`. Add `--account <id>` for an account other than the active one. `kortix billing status` and `kortix billing transactions` show credits. `kortix billing costs` shows money amounts. `--json` keeps the money amounts the API returns.

For scripts, the same reports are on the REST API. An account-wide read needs `billing.read`. A read with `project_id` needs `project.gateway.spend.read` on that project. A project-scoped token needs `project.usage.read` and its own `project_id`.

| Route | Returns |
| --- | --- |
| `GET /v1/usage/cost-summary` | Totals, a daily series and a model breakdown |
| `GET /v1/usage/cost-by-project` | Spend per project. `format=csv` for CSV. |
| `GET /v1/usage/session-costs` | Spend per session. `format=csv` for CSV. |
| `GET /v1/usage/session-costs/{sessionId}` | One session's model usage and charges |
| `GET /v1/usage` | Token and cost rollup. `group_by=model`, `provider` or `day`. |

The cost routes take `from`, `to` (half-open, UTC) and `project_id`. See the [REST API](/docs/api) for every field.

Account reports count what Kortix charged: `total_cost` = `llm_cost` + `compute_cost`. Spend on your own provider key is left out of `total_cost`. The reports return it separately as `llm_provider_cost`. The project **Costs** tab and the gateway logs split each model request into `kortix_cost` (from the wallet), `provider_cost` (paid to your provider) and `total_cost`.

## Spend less

- **Match the model to the work.** Send easy tasks to a smaller model.
- **Write clear instructions.** A well-defined task needs fewer turns.
- **Stay in one session.** Repeated turns in one session reuse the prompt cache.
- **Right-size the sandbox.** Compute meters the reserved spec, so do not reserve more `cpu`, `memory` or `disk` than the work needs.
- **Check Usage.** `kortix billing costs --by session` lists the costliest sessions first. Fix those first.

For a billing question, email [support@kortix.com](mailto:support@kortix.com) or ask in [Discord](https://discord.com/invite/RvFhXUdZ9H).