---
title: "Read the account credit balance, spend-based runway estimate and any credit notice"
method: GET
path: "/v1/balance"
---

# Read the account credit balance, spend-based runway estimate and any credit notice

`GET /v1/balance`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/balance`
- Auth: HTTP bearer

The account's current credit balance, plus `runway` (an estimate of how many days the balance lasts at the current spend rate) and `notice` (the same notice shown on the portal's overview page, `null` when there is none) - both ADDITIVE, so a client that only reads `balanceHal`/`balanceCzk`/`currency` keeps working. Also `topupBalanceHal` (the topped-up part, negative when the account owes) and `subscription` (the monthly plan, or `null`): `balanceHal` stays the TOTAL of the monthly plan credit and the topped-up credit.

## Response `200`

Current balance with runway and notice

- object
  - `balanceHal` number, required: Total credit in hellers: the monthly plan credit that is left plus the topped-up credit. Negative when the topped-up credit is in debt.
  - `balanceCzk` number, required
  - `currency` 'CZK', required
  - `runway` object, required
    - `dailyAverageHal` number, required
    - `runwayDays` number, nullable, required
  - `topupBalanceHal` number, required: The topped-up part of balanceHal in hellers: top-ups, bonus and adjustments. It does not expire. Negative when the account owes (debt); the monthly plan credit is never negative.
  - `subscription` object, nullable, required: The account's monthly plan, or null when it never had one. A plan that has ended is still returned, with status canceled.
    - `tier` '490' | '990' | '1990', required: Tier that is paid for the current period.
    - `status` 'active' | 'past_due' | 'canceled', required: active: the current period is paid. past_due: the last renewal payment failed and retries continue (monthly credit is 0 until it is paid; pay by hand with POST /v1/subscription/pay). canceled: the plan has ended.
    - `periodStart` string, required: Start of the paid period as an ISO 8601 string in UTC. Unlike the *At fields elsewhere in the API, which are Unix milliseconds, this is a string.
    - `periodEnd` string, required: End of the paid period as an ISO 8601 string in UTC: when the saved card is charged for the next one, unless the plan is canceled.
    - `monthlyCreditHal` number, required: Monthly credit of the paid tier, in hellers.
    - `monthlyRemainingHal` number, required: What is left of the monthly credit in this period, in hellers. It is spent first and what remains expires at the end of the period.
    - `exhaustionMode` 'topup' | 'cap', required: What happens once the monthly credit is used up. topup: credit is bought with the saved card (the account's auto top-up). cap: nothing more is bought; outbound actions fail with subscription_cap_reached until the next renewal.
    - `cancelAtPeriodEnd` boolean, required: true when the plan is canceled and ends at periodEnd without another charge. Until then the monthly credit stays usable.
    - `nextTier` '490' | '990' | '1990', nullable, required: Tier that takes effect from the next period, or null when the tier does not change.
    - `card` object, required: The saved card that renewals are charged to. Only the brand and the last four digits are ever returned.
      - `brand` string, nullable, required: Card brand, for example visa, or null when unknown.
      - `last4` string, nullable, required: Last four digits of the saved card, or null when unknown.
  - `notice` union, required
    - object
      - `kind` 'unknown', required
    - object
      - `kind` 'empty', required
    - object: Monthly fees for voice numbers or SMS numbers fall due within 3 days and the positive balance does not cover them. feeHal is the sum of all such fees in hellers, dueAt the earliest due time as a Unix epoch timestamp in milliseconds. Not returned while auto top-up is on.
      - `kind` 'number_fee', required
      - `feeHal` number, required
      - `dueAt` number, required
    - object
      - `kind` 'runway', required
      - `days` number, required
    - object: The monthly plan credit for this period is used up and the plan runs with exhaustionMode topup, so further use is paid from topped-up credit (auto top-up from the saved card). renewsAt is when the next monthly credit arrives, as a Unix epoch timestamp in milliseconds.
      - `kind` 'subscription_exhausted_topup', required
      - `renewsAt` number, required
    - object: The monthly plan credit for this period is used up, the plan runs with exhaustionMode cap and the remaining topped-up credit is gone, so paid actions stop until renewsAt (Unix epoch timestamp in milliseconds) or until the account tops up credit by hand.
      - `kind` 'subscription_cap_reached', required
      - `renewsAt` number, required
    - object: The plan's renewal payment failed and the plan is past due: the saved card could not be charged. Pay the renewal in the portal or replace the card; the plan ends after the retry attempts run out.
      - `kind` 'subscription_past_due', required
    - object: At the plan's cautious spending pace the balance runs out before the plan renews: runsOutAt is the estimate of when it runs out and renewsAt is when the next monthly credit arrives, both Unix epoch timestamps in milliseconds. The pace is the highest of the 28-day average (when the credit history covers the whole window), the average of the last 7 days and the average since the current period started (after its first week), the same pace as the monthly credit outlook on the plan card in the portal; runway keeps the 28-day average. Returned instead of runway on an account with an active plan (with exhaustionMode cap the agent stops answering once the debt limit is reached; with topup the card buys more credit). Nothing is returned while auto top-up is on.
      - `kind` 'subscription_runway', required
      - `renewsAt` number, required
      - `runsOutAt` number, required

## Other responses

- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `503`: Error codes: ledger_unavailable (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)