Balance and usage

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.

Try it in the console

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

Credit prices live on 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.
`403`	`billing_scope_required` — the `km_` key lacks `billing:read`. `owner_required` — a member key called `GET /v1/balance/history`.