---
title: "Balance and usage"
description: "GET /v1/balance, ledger, history, forecast, health, and GET /v1/usage — workspace credits behind billing:read."
canonical: "https://kingminos.com/docs/api/balance/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';

Read-only credit and usage routes at `https://api.kingminos.com`. They do not grant credits, sweep buckets, or change keys.

A signed-in session can call them. A `km_` workspace token needs the `billing:read` scope — it is not implied by `capability:*`. New `km_` tokens include `billing:read` by default. Tenant `osr_` keys are `401`. See [Authentication](/docs/api/authentication/).

<TryItLink method="GET" path="/v1/balance" />

```bash
curl 'https://api.kingminos.com/v1/balance' \
  -H 'Authorization: Bearer <your-key>'
```

Credit prices live on [Pricing](https://kingminos.com/pricing/). This page is the read contract only.

## `GET /v1/balance`

Workspace credit snapshot.

The response includes spendable `available` credits, in-flight holds, a `by_kind` breakdown, owner-only `buckets[]` (without `source_ref`), free-daily status including `will_grant_on_next_call` (the GET does not grant), plan and PAYG estimates, `refills` / `next_refill`, and per-key rolling 24-hour spend.

`payg` includes `enabled`, `monthly_limit_credits`, `used_this_cycle`, `used_this_cycle_usd_estimate`, `cycle_resets_at`, and `frozen`. Each `refills[]` row has `source`, `at`, `amount_credits`, and `estimated`.

## `GET /v1/balance/ledger`

Paginated credit ledger, newest first. Each row has a signed `delta` and allow-listed `source` / `ref` — raw payment or promo memos are not echoed.

Query: `since`, `until`, `kind`, `key_id`, `user_id`, and `before` (cursor).

Member keys only see their own `run` / `refund` rows (`visibility: self`). Owners and sessions see the workspace.

## `GET /v1/balance/history`

UTC day or hour series built from ledger `balance_after`, with carry-forward across quiet periods and a window `summary`. Balances exclude in-flight holds.

Owner or session only. Member keys get `403` `owner_required`.

Day series cover at most 400 days; hour series cover at most 7 days.

## `GET /v1/usage`

Run aggregates for the workspace: charged calls versus no-charge calls, plus ledger reconciliation. Optional `group_by`. Optional `since` / `until` and `capability`.

A charged call is one that spent credits — not one that succeeded. Member keys see a reduced view.

## `GET /v1/balance/forecast`

Runout projection from trailing run debit rates. Returns conservative and refill-aware runout, status, shortfall, and advice. Frozen PAYG is excluded from refill-aware math.

## `GET /v1/balance/health`

Balance health from the same forecast. Optional `?capability=` checks whether the workspace can afford that capability **without reserving credits**.

## Errors

| Status | When |
| --- | --- |
| `401` | Missing, malformed, or mismatched Bearer token. Tenant `osr_` keys are `401` here. See [Authentication](/docs/api/authentication/). |
| `403` | `billing_scope_required` — the `km_` key lacks `billing:read`. `owner_required` — a member key called `GET /v1/balance/history`. |