volai-cz Balance API
The Balance API from volai-cz — 1 operation(s) for balance.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/volai-cz:volai-cz-balance-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: volai REST Balance API
version: 1.49.0
description: 'Czech Twilio for vibecoders: numbers, calls, SMS and an AI voice agent through one REST API. All requests and responses are in English, regardless of the account''s language.'
servers:
- url: https://volai.cz
security:
- bearer: []
tags:
- name: Balance
paths:
/v1/balance:
get:
operationId: get_balance
summary: Read the account credit balance, spend-based runway estimate and any credit…
description: '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.'
responses:
'200':
description: Current balance with runway and notice
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
RateLimit-Limit:
description: Maximum authenticated requests in the current rate-limit window.
schema:
type: integer
RateLimit-Remaining:
description: Authenticated requests remaining in the current rate-limit window.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the authenticated rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
balanceHal:
type: number
description: '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:
type: number
currency:
type: string
const: CZK
runway:
type: object
properties:
dailyAverageHal:
type: number
runwayDays:
anyOf:
- type: number
- type: 'null'
required:
- dailyAverageHal
- runwayDays
topupBalanceHal:
type: number
description: '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:
anyOf:
- type: object
properties:
tier:
type: string
enum:
- '490'
- '990'
- '1990'
description: Tier that is paid for the current period.
status:
type: string
enum:
- active
- past_due
- canceled
description: '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:
type: string
description: 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:
type: string
description: '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:
type: number
description: Monthly credit of the paid tier, in hellers.
monthlyRemainingHal:
type: number
description: 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:
type: string
enum:
- topup
- cap
description: '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:
type: boolean
description: true when the plan is canceled and ends at periodEnd without another charge. Until then the monthly credit stays usable.
nextTier:
anyOf:
- type: string
enum:
- '490'
- '990'
- '1990'
- type: 'null'
description: Tier that takes effect from the next period, or null when the tier does not change.
card:
type: object
properties:
brand:
anyOf:
- type: string
- type: 'null'
description: Card brand, for example visa, or null when unknown.
last4:
anyOf:
- type: string
- type: 'null'
description: Last four digits of the saved card, or null when unknown.
required:
- brand
- last4
description: The saved card that renewals are charged to. Only the brand and the last four digits are ever returned.
required:
- tier
- status
- periodStart
- periodEnd
- monthlyCreditHal
- monthlyRemainingHal
- exhaustionMode
- cancelAtPeriodEnd
- nextTier
- card
- type: 'null'
description: The account's monthly plan, or null when it never had one. A plan that has ended is still returned, with status canceled.
notice:
anyOf:
- anyOf:
- type: object
properties:
kind:
type: string
const: unknown
required:
- kind
- type: object
properties:
kind:
type: string
const: empty
required:
- kind
- type: object
properties:
kind:
type: string
const: number_fee
feeHal:
type: number
dueAt:
type: number
required:
- kind
- feeHal
- dueAt
description: Monthly fees for voice numbers, SMS numbers or calls and 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.
- type: object
properties:
kind:
type: string
const: runway
days:
type: number
required:
- kind
- days
- type: object
properties:
kind:
type: string
const: subscription_exhausted_topup
renewsAt:
type: number
cancelAtPeriodEnd:
type: boolean
const: true
required:
- kind
- renewsAt
description: '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. renewsAt is the same moment as subscription.periodEnd in the same response, which is an ISO 8601 string. cancelAtPeriodEnd: true is present only when the plan is set to end after the paid period: no renewal follows, renewsAt is then the end of the plan and no new monthly credit arrives.'
- type: object
properties:
kind:
type: string
const: subscription_cap_reached
renewsAt:
type: number
cancelAtPeriodEnd:
type: boolean
const: true
required:
- kind
- renewsAt
description: '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. renewsAt is the same moment as subscription.periodEnd in the same response, which is an ISO 8601 string. cancelAtPeriodEnd: true is present only when the plan is set to end after the paid period: no renewal follows, renewsAt is then the end of the plan and no new monthly credit arrives.'
- type: object
properties:
kind:
type: string
const: subscription_past_due
required:
- kind
description: '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.'
- type: object
properties:
kind:
type: string
const: subscription_runway
renewsAt:
type: number
runsOutAt:
type: number
cancelAtPeriodEnd:
type: boolean
const: true
required:
- kind
- renewsAt
- runsOutAt
description: '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. renewsAt is the same moment as subscription.periodEnd in the same response, which is an ISO 8601 string. cancelAtPeriodEnd: true is present only when the plan is set to end after the paid period: no renewal follows, renewsAt is then the end of the plan and no new monthly credit arrives.'
- type: 'null'
required:
- balanceHal
- balanceCzk
- currency
- runway
- topupBalanceHal
- subscription
- notice
'401':
description: 'Error codes: unauthorized (request).'
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
WWW-Authenticate:
description: Bearer authentication challenge for an invalid or missing API key.
schema:
type: string
example: Bearer realm="volai", error="invalid_token"
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
cause:
type: string
enum:
- request
- account
- busy
- service
message:
type: string
action:
type: string
currentRevision:
type: number
details:
type: object
properties:
reason:
type: string
const: task_changed_during_registration
providerActionStarted:
type: boolean
const: false
operationId:
type: string
required:
- reason
- providerActionStarted
- operationId
confirmUrl:
description: 'Only on subscription_confirmation_required (409): the portal page where a person signed in to the account confirms the change. Valid for 24 hours and usable once.'
type: string
requestId:
type: string
docsUrl:
type: string
required:
- code
- cause
- message
- action
- requestId
- docsUrl
required:
- error
'403':
description: 'Error codes: account_suspended (account).'
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
RateLimit-Limit:
description: Maximum authenticated requests in the current rate-limit window.
schema:
type: integer
RateLimit-Remaining:
description: Authenticated requests remaining in the current rate-limit window.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the authenticated rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
cause:
type: string
enum:
- request
- account
- busy
- service
message:
type: string
action:
type: string
currentRevision:
type: number
details:
type: object
properties:
reason:
type: string
const: task_changed_during_registration
providerActionStarted:
type: boolean
const: false
operationId:
type: string
required:
- reason
- providerActionStarted
- operationId
confirmUrl:
description: 'Only on subscription_confirmation_required (409): the portal page where a person signed in to the account confirms the change. Valid for 24 hours and usable once.'
type: string
requestId:
type: string
docsUrl:
type: string
required:
- code
- cause
- message
- action
- requestId
- docsUrl
required:
- error
'429':
description: 'Error codes: rate_limited (busy).'
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
RateLimit-Limit:
description: Maximum authenticated requests in the current rate-limit window.
schema:
type: integer
RateLimit-Remaining:
description: Authenticated requests remaining in the current rate-limit window.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the authenticated rate-limit window resets.
schema:
type: integer
Retry-After:
description: 'Seconds until the request may be retried. Sent for the API key limit and for the outbound call limit when the wait is known. Other 429 responses, for example the daily SMS cap or a number purchase that is still running, do not carry it: follow the error message instead.'
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
cause:
type: string
enum:
- request
- account
- busy
- service
message:
type: string
action:
type: string
currentRevision:
type: number
details:
type: object
properties:
reason:
type: string
const: task_changed_during_registration
providerActionStarted:
type: boolean
const: false
operationId:
type: string
required:
- reason
- providerActionStarted
- operationId
confirmUrl:
description: 'Only on subscription_confirmation_required (409): the portal page where a person signed in to the account confirms the change. Valid for 24 hours and usable once.'
type: string
requestId:
type: string
docsUrl:
type: string
required:
- code
- cause
- message
- action
- requestId
- docsUrl
required:
- error
'500':
description: 'Error codes: internal_error (service).'
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
RateLimit-Limit:
description: Maximum authenticated requests in the current rate-limit window.
schema:
type: integer
RateLimit-Remaining:
description: Authenticated requests remaining in the current rate-limit window.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the authenticated rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
cause:
type: string
enum:
- request
- account
- busy
- service
message:
type: string
action:
type: string
currentRevision:
type: number
details:
type: object
properties:
reason:
type: string
const: task_changed_during_registration
providerActionStarted:
type: boolean
const: false
operationId:
type: string
required:
- reason
- providerActionStarted
- operationId
confirmUrl:
description: 'Only on subscription_confirmation_required (409): the portal page where a person signed in to the account confirms the change. Valid for 24 hours and usable once.'
type: string
requestId:
type: string
docsUrl:
type: string
required:
- code
- cause
- message
- action
- requestId
- docsUrl
required:
- error
'503':
description: 'Error codes: ledger_unavailable (service).'
headers:
X-Request-Id:
description: Unique request ID for this response, in the form req_ followed by 16 hexadecimal characters.
schema:
type: string
pattern: ^req_[0-9a-f]{16}$
X-Volai-Version:
description: Current public interface version. If it changed, read GET /v1/changelog.
schema:
type: string
RateLimit-Limit:
description: Maximum authenticated requests in the current rate-limit window.
schema:
type: integer
RateLimit-Remaining:
description: Authenticated requests remaining in the current rate-limit window.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the authenticated rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
cause:
type: string
enum:
- request
- account
- busy
- service
message:
type: string
action:
type: string
currentRevision:
type: number
details:
type: object
properties:
reason:
type: string
const: task_changed_during_registration
providerActionStarted:
type: boolean
const: false
operationId:
type: string
required:
- reason
- providerActionStarted
- operationId
confirmUrl:
description: 'Only on subscription_confirmation_required (409): the portal page where a person signed in to the account confirms the change. Valid for 24 hours and usable once.'
type: string
requestId:
type: string
docsUrl:
type: string
required:
- code
- cause
- message
- action
- requestId
- docsUrl
required:
- error
tags:
- Balance
components:
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: vk_...
description: 'API key from the API and MCP page of the volai portal (/en/api-and-mcp), sent as `Authorization: Bearer vk_...`.'