> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boltroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve user balance

> Retrieve the current user credit balance.

## Base URL

* **Production:** `https://api.boltroute.ai`
* **Staging:** `https://staging-api.example.com`
* **Local:** `http://localhost:8080`

## Conventions

* **Content-Type:** `application/json`
* **Date/Time:** ISO 8601 (UTC)
* **Pagination:** `limit`, `offset`
* **Error format:** JSON error payload with `code`, `message`, and optional `details`

Example error payload:

```json theme={null}
{
  "error": {
    "code": "STRING_CODE",
    "message": "Human readable message",
    "details": [
      { "field": "fieldA", "reason": "required" }
    ]
  }
}
```

***

# Endpoints

## GET /api/v1/credits/balance

**Summary:** Return the current credit balance for the authenticated user.

**Idempotent:** Yes
**Tags:** credits

### Request

**Headers**

* `Content-Type: application/json`

**Query Params**

| Name | Type | Required | Default | Description | Example |
| ---- | ---- | -------- | ------- | ----------- | ------- |

### Responses

**200 OK - Credit balance**

```json theme={null}
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "balance": 500
}
```

**Response Fields**

| Field    | Type    | Description            |
| -------- | ------- | ---------------------- |
| user\_id | string  | User UUID              |
| balance  | integer | Current credit balance |

**400 Bad Request - Invalid query parameters**

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "user_id must be a valid UUID"
  }
}
```

**401 Unauthorized**

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token"
  }
}
```

**404 Not Found**

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}
```

**500 Internal Server Error**

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected server error"
  }
}
```

### Examples

**cURL**

```bash theme={null}
curl -X GET \
  'https://api.boltroute.ai/api/v1/credits/balance'
```

***