# Get the wallet balance

`getWallet`

`GET /v1/wallet`

The organization's Credits balance. A billing key needs the billing:read scope; a project key needs balance:read and reads the balance of the organization its project belongs to.

## Authentication

Send your project key in the request header, for example `Authorization: Bearer $VIZO_API_KEY`. Keep the key on your server.

## Responses

### 200 OK

- `available` (string, Required) Credits you can spend now.
- `balance` (string, Required) Spendable Credits minus owed, as a signed decimal. Spendable excludes Credits frozen for review, which stay in available but cannot be spent or repay owed Credits, so balance is negative exactly while Credits are owed.
- `has_purchased` (boolean, Optional) True once any purchase, including an auto top-up, has been credited to this organization, whatever the balance is now. Promotional, trial and compensation Credits do not count.
- `held` (string, Required) Credits held by running tasks.
- `owed` (string, Required) Credits owed: the part of a task's actual charge above its hold that the balance could not pay. A top-up repays it first. While it is above zero, new tasks are refused with balance_negative.
- `paid_available` (string, Required)
- `promotional_available` (string, Required)
- `refund_reserved` (string, Required)
- `total` (string, Required) Available plus held plus refunds in progress.
- `unit` (string, Required) Allowed values: `credit`

```json
{
  "available": "1843.000",
  "balance": "string",
  "has_purchased": false,
  "held": "157.000",
  "owed": "string",
  "paid_available": "1843.000",
  "promotional_available": "0.000",
  "refund_reserved": "0.000",
  "total": "2000.000",
  "unit": "credit"
}
```

### 400 Bad Request

```json
{
  "error": {
    "code": "invalid_input",
    "message": "The request body could not be read as JSON.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 401 Unauthorized

```json
{
  "error": {
    "code": "invalid_credentials",
    "message": "API key is missing, malformed, expired or revoked.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 403 Forbidden

```json
{
  "error": {
    "code": "scope_denied",
    "message": "The key does not allow this operation for this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 404 Not Found

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is not available to this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 409 Conflict

```json
{
  "error": {
    "code": "conflict",
    "message": "The request conflicts with the current state of the resource.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 422 Unprocessable Entity

```json
{
  "error": {
    "code": "invalid_input",
    "message": "Input does not match the published schema.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 429 Too Many Requests

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Check Retry-After.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 500 Internal Server Error

```json
{
  "error": {
    "code": "request_failed",
    "message": "The request failed. Check recent generations before submitting again.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

### 503 Service Unavailable

```json
{
  "error": {
    "code": "temporarily_unavailable",
    "message": "Service is temporarily unavailable.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}
```

## Errors

Errors share one body. Include the request_id when you contact support.

### Error body

- `error` (object, Required) Details of the error.
  - `code` (string, Required) Stable request error code. invalid_input rejects the request schema; invalid_credentials/scope_denied reject authentication/authorization; ip_not_allowed/model_not_allowed reject API key IP/model restrictions; resource_not_found hides missing or inaccessible resources; conflict rejects incompatible state; insufficient_balance/budget_exceeded/spending_blocked reject funding; balance_negative (402) refuses new tasks while the organization owes Credits from a charge above its hold, until a top-up repays them; rate_limited/concurrency_limited ask for a later retry; temporarily_unavailable is transient service capacity; request_failed covers other HTTP failures. tier_not_sold, draft_not_found, draft_expired and input_duration_out_of_range reject model-specific input. input_media_invalid rejects a detected format/type mismatch; input_media_too_large rejects a probed byte size above the model limit. storage_quota_exceeded rejects an upload when the organization's storage is full. See errors for field-level details. Allowed values: `invalid_input`, `invalid_credentials`, `insufficient_balance`, `balance_negative`, `scope_denied`, `resource_not_found`, `conflict`, `rate_limited`, `concurrency_limited`, `temporarily_unavailable`, `request_failed`, `ip_not_allowed`, `model_not_allowed`, `tier_not_sold`, `draft_not_found`, `draft_expired`, `input_duration_out_of_range`, `input_media_invalid`, `input_media_too_large`, `budget_exceeded`, `spending_blocked`, `storage_quota_exceeded`
  - `errors` (object[], Optional, can be null)
    - `path` (string, Required)
    - `rule` (string, Required)
  - `message` (string, Required) Readable explanation. Do not parse it.
  - `request_id` (string, Required) Include this when you contact support.
  - `retryable` (boolean, Required) True for 429 and 503 only. Even then, check recent tasks before you send a create request again.
  - `task_id` (string, Optional) The task this error belongs to, when one exists.

| Status | What it means and what to do |
| --- | --- |
| 400 | The request could not be read. Check the query values against the table above. |
| 401 | The key is missing, malformed, expired or revoked. Correct the key on your server, then continue. |
| 403 | The key scope, email verification, a budget or an account restriction blocks this. Check the key type, scopes and project budget. |
| 404 | The model or resource does not exist or is outside this project. Check the project, the ID and that the model is enabled. |
| 409 | The request conflicts with the current state. Read the resource again and decide whether to send the request again. |
| 422 | A field or value is invalid. Compare the request with the field table and the model page. |
| 429 | Too many requests. No task was created. Wait for the Retry-After time before sending again. |
| 500 | The server failed and the task may already be accepted. Do not resend; list recent tasks first. |
| 503 | The service is temporarily unavailable. For a create request, list recent tasks and confirm none was accepted before you submit again. |

### cURL

```bash
curl "https://api.vizoapi.com/v1/wallet" \
  -H "Authorization: Bearer $VIZO_API_KEY"
```

### Python

```python
import os, requests

res = requests.get(
    "https://api.vizoapi.com/v1/wallet",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    timeout=60,
)
print(res.status_code, res.json())
```

### Node.js

```javascript
const res = await fetch("https://api.vizoapi.com/v1/wallet", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```