Usage and quota

GET https://api.vizvuz.com/v1/usage

One call tells you where you stand in the current billing period.

Response

curl https://api.vizvuz.com/v1/usage \
  -H "Authorization: Bearer vz_live_xxxxxxxx"

On a subscription:

{
  "character_count": 412903,
  "character_limit": 2000000,
  "billing": {
    "mode": "subscription",
    "plan": "starter",
    "currency": "EUR",
    "period_end": "2026-10-01T00:00:00Z",
    "overage_characters": 0,
    "credit_balance": null
  }
}

On pay as you go:

{
  "character_count": 87211,
  "character_limit": 100000,
  "billing": {
    "mode": "credit",
    "plan": "payg",
    "currency": "EUR",
    "period_end": null,
    "overage_characters": 0,
    "credit_balance": "1.912835"
  }
}

Field	Meaning
`character_count`	Characters used in the current period
`character_limit`	Included volume, or the characters your remaining credit buys
`billing.mode`	`subscription` or `credit`
`billing.period_end`	End of the current period, `null` for pay as you go
`billing.overage_characters`	Characters already recorded above the included volume
`billing.credit_balance`	Remaining credit as a decimal string, `null` on a subscription

credit_balance is a string on purpose. It carries six decimal places, which no binary float represents exactly. Parse it as a decimal, or compare it as text.

How a request consumes quota

The key is resolved and the rate limit checked.
The request is validated and its characters counted.
The characters are reserved atomically, before any translation happens.
The cache is checked, then the engine is called.
If anything fails, the reservation is rolled back in full.
After the response is sent, a usage event is written asynchronously.

That order is why a failed request never costs you anything, and why two parallel requests can never spend the same last thousand characters twice.

Subscriptions: included volume, overage and the cap

Usage inside the included volume is covered by the base fee. Above it, usage is recorded per started 100,000 characters at your plan's overage rate and charged at the end of the period.

Every team has an overage cap — 50 EUR by default, adjustable in the dashboard, and settable to unlimited. When the cap is reached the API answers 402 with quota_exceeded and stops translating. That is deliberate: an unnoticed loop should cost you an error, not a four-figure invoice.

You get a warning e-mail at 80 % and at 100 % of the included volume.

Pay as you go: prepaid credit

Credit is bought up front, from 10 to 2,000 EUR per top-up, and is valid for twelve months. You get an e-mail thirty days before any part of it expires. When it runs out, the API answers 402 with credit_exhausted.

Internally, credit is held in integer units of one ten-thousandth of a minor currency unit, so per-character pricing stays exact at any volume. No rounding happens until an invoice line is written.

Monitoring it

Poll /v1/usage every few minutes rather than after every translation — the figures are eventually consistent within a second or two, and polling harder tells you nothing new. For a per-key, per-language-pair breakdown, use the usage page in the dashboard, which also exports CSV.

What we do not store

We store counters, never content. A usage record holds the team, the key, the request id, the character count, the language pair, whether it was a cache hit, the latency and what it cost. Your source text and the translation are not in it.

Last updated Sep 1, 2026, 12:00 AM