GET /v1/balance

This read-only endpoint returns the account wallet and the most restrictive configured Usage Limit for the authenticated key. It requires an active, unexpired API key and the current domain, account and IP permissions. A zero wallet or an exhausted Usage Limit does not prevent this lookup.

Request

curl https://api.model-gate.com/v1/balance \
  -H "Authorization: Bearer mg_live_..."

Response

{
  "object": "balance",
  "currency": "USD",
  "balance": "12.34",
  "key": {
    "limit": "100.0000000000",
    "usage": "30.0000000000",
    "remaining": "70.0000000000",
    "limit_source": "key"
  }
}

The existing object, currency and balance fields keep their meaning. balance is the billing owner's wallet in USD, represented as a decimal string; insignificant trailing zeros may be omitted. The new key object describes a quota, not a separate wallet or a guaranteed spendable amount. Its monetary values, other than null, are decimal strings with ten fractional digits. Keep the strings exact in financial code instead of converting them to binary floating-point numbers.

Selecting the Usage Limit

Only positive configured key or group limits participate. For each participating counter, the remainder is max(0, limit - usage):

All three values come from the selected source. When limit_source is "group", usage is the group's aggregate usage, not the individual key's usage. For example, a key remainder of 6 and a group remainder of 3 return the group's values. The source is selected by remaining quota, not by the smaller configured limit.

An exhausted or overspent configured limit returns "0.0000000000"; it does not fall back to another counter or the wallet. Actual usage is preserved even when it exceeds the limit. With no limits, a response can contain:

{
  "key": {
    "limit": null,
    "usage": "3.5000000000",
    "remaining": null,
    "limit_source": null
  }
}

Here null means that neither Usage Limit is configured. It does not mean zero funds or unlimited account credit. Keys and groups have independent resettable usage counters; lifetime spending is not substituted for usage. An authorized usage reset can change the selected source on the next lookup.

Wallet and quota are separate

The wallet does not cap key.remaining. Usage valuation may use the user price or official price with its configured multiplier, independently of the actual wallet charge. The endpoint reports the stored counters without converting between these valuations. In the first example, a quota remainder of 70 therefore remains 70 even though the wallet contains 12.34 USD.

The response reflects recorded wallet and usage values. Unfinished work and completed requests awaiting settlement may not yet be reflected. No money is reserved by this GET request, and the returned numbers do not guarantee that a future request can run. Existing wallet, key/group, model, rate and access checks continue to apply to inference.

Business visibility

For Individual credentials, the wallet belongs to the user who owns the key. For Business credentials, charges use the company owner's wallet. The shared company balance is returned only when the credential principal has company-level balance visibility: organization owner, admin or an authorized billing role. Employee credentials without that right receive HTTP 403 from this endpoint, including its key object. A project role or knowledge of a key does not grant company wallet visibility.

Authentication error

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

Business permission error

{
  "error": {
    "type": "permission_error",
    "code": "balance_not_permitted",
    "message": "Company balance is not available for this credential principal."
  }
}