# Get balance

GET https://fusara.ai/api/v3/balance

The current payer's Common Fuz ledger balance and accepted unpaid commitments, across all keys and execution channels. available = balance - reserved. This is a current snapshot, not an entitlement or a reservation. New runs still perform atomic budget admission. A valid zero balance is 200; a dependency outage is 503 balance_unavailable.

## Example request

```bash
curl 'https://fusara.ai/api/v3/balance' \
  -H "Authorization: Bearer $FUSARA_API_KEY"
```

## Parameters


## Responses

### 200

OK

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

```json
{
  "unit": "common_fuz",
  "balance": "1200.0000",
  "reserved": "160.0000",
  "available": "1040.0000"
}
```

#### Response body

- `unit` (string, required): Billing unit: common_fuz.
- `balance` (string, required): Current payer ledger balance, as a decimal string.
- `reserved` (string, required): Accepted unpaid commitments across the payer's execution channels, as a decimal string.
- `available` (string, required): balance minus reserved, as a decimal string. This snapshot can be negative.

### 400

invalid_header: supply only one authentication header, Authorization: Bearer or X-API-Key.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 401

authentication_required: the API key is missing or invalid. Public methods allow omission, but reject invalid supplied credentials.

#### Response headers

- `WWW-Authenticate` (string, required): Bearer authentication challenge. Values: "Bearer".
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 422

validation_error: correct the fields identified by error.errors[].pointer; unknown fields and query parameters are rejected.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 429

rate_limited (retryable: true): wait for the indicated delay, then retry. Use bounded backoff if no delay is supplied.

#### Response headers

- `Retry-After` (integer): When supplied, the minimum number of seconds to wait before retrying a transient failure. Preserve the original idempotency key and body when retrying a submission. Minimum: 1.
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 500

internal_error: unexpected server failure. Contact support if the failure persists; inspect error.retryable before retrying automatically.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 503

balance_unavailable (retryable: true): the balance dependency is temporarily unavailable. Wait for the indicated delay and retry; zero balance is a successful 200 response.

#### Response headers

- `Retry-After` (integer): When supplied, the minimum number of seconds to wait before retrying a transient failure. Preserve the original idempotency key and body when retrying a submission. Minimum: 1.
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.