Usage and quota

GET https://api.langapi.xyz/v1/usage

The endpoint reports your team's position in the current billing period: what has been used, what is still available and which billing mode applies.

The call

curl https://api.langapi.xyz/v1/usage \
  -H "Authorization: Bearer la_live_xxxxxxxx"

Fields

credit_balance is a string because six decimal places do not survive a round trip through a binary float. Parse it with a decimal type, or leave it as text for display.

Example: Business subscription

{
  "character_count": 6218450,
  "character_limit": 15000000,
  "billing": {
    "mode": "subscription",
    "plan": "business",
    "currency": "EUR",
    "period_end": "2026-10-01T00:00:00Z",
    "overage_characters": 0,
    "credit_balance": null
  },
  "engine": { "prompt_tokens": 4102377, "completion_tokens": 3311908, "total_tokens": 7414285 }
}

Example: prepaid credit

{
  "character_count": 14320,
  "character_limit": 100000,
  "billing": {
    "mode": "credit",
    "plan": "payg",
    "currency": "EUR",
    "period_end": null,
    "overage_characters": 0,
    "credit_balance": "1.285200"
  },
  "engine": { "prompt_tokens": 19864, "completion_tokens": 15130, "total_tokens": 34994 }
}

Reserve first, translate second

A translate request moves through these stages in order:

1. Authentication and the per-second rate limit.
2. Parameter validation and the character count.
3. An atomic reservation of that many characters against the quota or the

credit balance. Two concurrent requests cannot both take the last slice.

1. Cache lookup, then the engine call for whatever was not cached.
2. On any failure after step 3, the reservation is released in full.
3. After the response has been sent, a usage record is written in the

background.

Consequences: a request that ends in an error is never charged, and a 402 is raised before the engine is ever contacted.

Subscriptions: included volume, overage and the cap

Characters inside the included volume are covered by the plan fee. Beyond it, every further character is recorded as overage at your plan's overage rate, which is listed on the pricing page.

Every subscription has an overage cap in your billing currency. It is set in the dashboard and can be raised, lowered or switched off entirely. When a request would push the period's overage past the cap, the API answers 402 with quota_exceeded and includes character_limit, overage_cap_minor and period_end in the problem document. Translation resumes when the cap is raised or the next period begins.

Prepaid credit

Without a subscription the team runs on credit. A verified account starts with credit for 100,000 characters; that welcome credit expires twelve months after it was granted. Top-ups are bought in the dashboard, within the minimum and maximum shown on the pricing page.

Each request deducts the exact cost of its characters. Internally the balance is kept in units of one ten-thousandth of a minor currency unit, which keeps per-character pricing exact without rounding until an invoice is produced. When the balance cannot cover a request, the API answers 402 with credit_exhausted; the document includes balance_minor, required_minor and currency.

Polling

The counters are updated at reservation time, so /v1/usage reflects a request as soon as it has been accepted. Polling once every few minutes is plenty; nothing changes faster than your own request rate. For a breakdown by key, day and language pair use the usage page in the dashboard.

CSV export

The dashboard exports one row per day, key and language pair:

date,api_key_id,source_lang,target_lang,characters,requests,cost_minor,prompt_tokens,completion_tokens

cost_minor is the amount charged for that row in minor currency units. The two token columns are engine statistics, described on Tokens versus billed characters.

What a usage record holds

Team, key, request id, character count, source and target language, whether the whole request was served from cache, latency, token counts and the amount charged. Neither the source text nor the translation is part of it.