---
title: "Tokens this key can spend"
method: GET
path: "/api/v1/balance"
tags: ["Public API v1"]
---

# Tokens this key can spend

`GET /api/v1/balance`

## Request

- Base URL: `https://api.vieneu.io`
- URL: `https://api.vieneu.io/api/v1/balance`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

`remaining` is the largest request the key can pay for right now. A request is paid by ONE plan — the key’s own plan when it can, otherwise another active plan of the account — so this is the most room any single plan has (the lowest of its total, daily and weekly caps), never a sum. `plan` details the plan that number is measured on. `spendableTokens` is the sum: what all the plans that may pay can still spend, request after request — the running total, which drops by each request’s cost. `totalRemainingTokens` sums every active plan on the account. The cost of a request is `characters (minimum 50) × engine billingMultiplier × globalMultiplier` — see GET /v1/engines.

## Response `200`

What this key can spend, and the plan that measures it.

- PublicBalanceResponseDto
  - `remaining` number, required: The largest request this key can pay for right now. A request is paid by ONE plan: the key’s own plan when it can, otherwise another active plan of the account that covers the default engine. This is the most room any single one of them has (the lowest of its total, daily and weekly caps) — never a sum. A request costing more is refused with 403 (or 429 for a daily/weekly cap).
  - `spendableTokens` number, required: What this key can spend in total right now, request after request: the room left on every plan that may pay its requests (its own plan, then the account’s other active plans that cover the default engine), each counted only up to its own daily and weekly caps, added up. Each request lowers it by what it cost, whichever of those plans paid. Equal to `remaining` when only one plan can pay. One request can still spend no more than `remaining`.
  - `plan` PublicBalancePlanDto
    - `totalTokens` number, required
    - `remainingTokens` number, required
    - `dailyRemaining` number, nullable: Daily cap left today; null when the plan has no daily cap.
    - `weeklyRemaining` number, nullable: Weekly cap left this week; null when the plan has no weekly cap.
    - `dailyResetAt` string, date-time, nullable: When the daily cap resets.
    - `weeklyResetAt` string, date-time, nullable: When the weekly cap resets.
    - `expiresAt` string, date-time, nullable: When the plan expires; null = no expiry.
    - `status` 'ACTIVE' | 'EXHAUSTED' | 'EXPIRED' | 'UPGRADED' | 'REVOKED', required
    - `isTrial` boolean, required
    - `isGift` boolean, required: True when this plan is a token gift from VieNeu (tokens with no package behind them: no daily or weekly cap, no expiry), not a package you bought or were given.
  - `activeGrants` number, required: Active plans on the account. When this key’s own plan cannot pay for a request, another one pays for it.
  - `totalRemainingTokens` number, required: Remaining tokens summed over every active plan of the account.

## Other responses

- `401`: API key missing, malformed, or revoked.

## Changes

- **2026-10-10** `8e42136d02f3`: 2 info
  - added the required property `plan/allOf[#/components/schemas/PublicBalancePlanDto]/isGift` to the response with the `200` status
  - added the required property `spendableTokens` to the response with the `200` status
- **2026-10-01** `82d83b635803`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vieneu/apis/vieneu-api/changes/api/v1/balance/get.md)

---

[API](https://skmtc.dev/vieneu/apis/vieneu-api.md) - [All operations](https://skmtc.dev/vieneu/apis/vieneu-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vieneu/apis/vieneu-api/revisions/9518b716e16d?raw)