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

# Get account balance

> Read the authenticated account balance

```http theme={null}
GET /user/billing/balance
```

This endpoint requires an **Account key**. Inference keys are not accepted.

## Request

```bash theme={null}
curl https://api.mulerouter.ai/user/billing/balance \
  -H "Authorization: Bearer $MULEROUTER_ACCOUNT_KEY"
```

## Response

```json theme={null}
{
  "user_id": "18b8e805-3dce-4f12-bbda-8c3cff9d7af4",
  "total_balance": 500000,
  "available_balance": 500000,
  "hold_balance": 0
}
```

Balance values use units of `0.0001 credits`. For example, `500000` equals `50 credits`.

| Field               | Description                |
| ------------------- | -------------------------- |
| `user_id`           | Authenticated user ID      |
| `total_balance`     | Total account balance      |
| `available_balance` | Balance available to spend |
| `hold_balance`      | Balance currently on hold  |

## Errors

| Status | Description                               |
| ------ | ----------------------------------------- |
| `401`  | Token is missing, invalid, or revoked     |
| `403`  | User account is suspended                 |
| `502`  | Wallet service request failed             |
| `503`  | Wallet service is temporarily unavailable |
| `500`  | Balance query failed                      |


## OpenAPI

````yaml api-reference/endpoint/user/billing/balance.yaml GET /user/billing/balance
openapi: 3.1.0
info:
  title: MuleRouter Account Balance API
  description: Query the balance of the account authenticated by an Account key.
  version: 1.0.0
servers:
  - url: https://api.mulerouter.ai/
security:
  - bearerAuth: []
paths:
  /user/billing/balance:
    get:
      summary: Get account balance
      description: >-
        Returns the current user's total, available, and held balances. Requires
        an Account key.
      operationId: getUserBillingBalance
      responses:
        '200':
          description: Account balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalance'
              example:
                user_id: 18b8e805-3dce-4f12-bbda-8c3cff9d7af4
                total_balance: 500000
                available_balance: 500000
                hold_balance: 0
        '401':
          description: Token is missing, invalid, or revoked
        '403':
          description: User account is suspended
        '500':
          description: Balance query failed
        '502':
          description: Wallet service request failed
        '503':
          description: Wallet service is temporarily unavailable
components:
  schemas:
    AccountBalance:
      type: object
      additionalProperties: false
      required:
        - user_id
        - total_balance
        - available_balance
        - hold_balance
      properties:
        user_id:
          type: string
          format: uuid
          description: Authenticated user ID
        total_balance:
          type: integer
          description: Total balance in units of 0.0001 credits
          example: 500000
        available_balance:
          type: integer
          description: Available balance in units of 0.0001 credits
          example: 500000
        hold_balance:
          type: integer
          description: Held balance in units of 0.0001 credits
          example: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Account key

````