Get the workspace's current Nurama Credit balance.
Returns the workspace's spendable Nurama Credit balance, sourced from the canonical `CreditBalance` row maintained atomically by the AI usage and grant flows. Requires `canGetCreditBalance` on the workspace (workspace owner / admin, project owner / admin) and an active subscription; no per-feature gate. The balance is also returned as `balanceAfter` on every billable AI call, so the FE can keep its display fresh without a separate fetch after every call. `balance` is the spendable total: `planBalance` (monthly plan grant, does not carry over) + `purchasedBalance` (top-ups, accumulates). `hasPriorTopUp` reports whether the workspace has ever made a manual credit purchase — the precondition for enabling auto top-up. Aliased at `GET /credits/balance` (same handler, same response).
Returns the workspace's spendable Nurama Credit balance, sourced from
the canonical CreditBalance row maintained atomically by the AI
usage and grant flows.
Requires canGetCreditBalance on the workspace (workspace owner /
admin, project owner / admin) and an active subscription; no
per-feature gate. The balance is also returned as balanceAfter on
every billable AI call, so the FE can keep its display fresh without
a separate fetch after every call.
balance is the spendable total: planBalance (monthly plan grant,
does not carry over) + purchasedBalance (top-ups, accumulates).
hasPriorTopUp reports whether the workspace has ever made a manual
credit purchase — the precondition for enabling auto top-up.
Aliased at GET /credits/balance (same handler, same response).
OAuth 2.1 authorization code flow with PKCE (required of every client, public or confidential). Scopes are a ceiling on the credential, not a grant of access: a token also cannot exceed what the user who approved it may already do. A write scope does not imply its matching read — ask for both.
In: header
Scope: ai:use
Query Parameters
Workspace whose Nurama Credit balance to retrieve.
uuidResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/ai/balance?workspaceId=497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "balance": 9997, "planBalance": 5000, "purchasedBalance": 4997, "hasPriorTopUp": true}