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

# Account Balance API

> Retrieve the identity and balance summary (balance, coupon, available, and frozen amounts) of the account that owns the API key.

## Overview

Use this endpoint to inspect the account behind your API key: its identity (email, user ID, name) and a balance summary in US dollars.

<Tip>
  Use `available_balance` to decide whether to issue new requests. It already accounts for amounts reserved by in-flight generation requests (`frozen_balance`), so no manual subtraction is needed.
</Tip>

## Endpoint

* `GET https://api.siray.ai/v1/account/balance`

**Headers**

* `Authorization: Bearer <SIRAY_API_TOKEN>`

## Response structure

```json theme={null}
{
  "request_uuid": "f1c2...",
  "code": 200,
  "message": "OK",
  "data": {
    "user_id": "user-3f8a2c1d",
    "user_name": "alice",
    "email": "alice@example.com",
    "balance": 123.45,
    "coupon_balance": 1.25,
    "available_balance": 121.10,
    "frozen_balance": 3.60
  }
}
```

### Fields

* `request_uuid`: Identifier of this API call, useful for support and log correlation.
* `code` / `message`: Service-level indicators for the request outcome (`200` / `OK` on success).
* `data.user_id`: ID of the account that owns the API key.
* `data.user_name`: Name of that account.
* `data.email`: Email of that account.
* `data.balance`: Account balance in USD.
* `data.coupon_balance`: Remaining coupon balance in USD (expired coupons excluded).
* `data.available_balance`: Balance you can actually spend, in USD:
  `available_balance = balance + coupon_balance − frozen_balance`.
* `data.frozen_balance`: Total amount currently reserved by in-flight requests, in USD. It is `0` when no amount is frozen.

All amounts are in **USD, rounded to two decimal places**.

## Usage example

```bash theme={null}
curl -X GET "https://api.siray.ai/v1/account/balance" \
  -H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```

> `frozen_balance` is reserved by in-flight generation requests and is released automatically once they settle or expire; `available_balance` recovers accordingly without any action on your side.

## Errors

The endpoint returns the standard response envelope. Non-`200` `code` values indicate failure and come with a `message` and no `data`.

| HTTP status | `code` | Typical cause                                                 |
| ----------- | ------ | ------------------------------------------------------------- |
| 401         | 401    | Missing or malformed `Authorization` header; unknown API key. |
| 403         | 403    | API key is disabled or expired, or the account is forbidden.  |
| 500         | 500    | Upstream (billing) validation failure; retry later.           |


## OpenAPI

````yaml openapi-spec/account-balance.json GET /v1/account/balance
openapi: 3.1.0
info:
  title: Account Balance API
  summary: Retrieve the account identity and balance summary
  description: >-
    Returns the identity (email, user ID, name) of the account that owns the API
    key, together with its balance summary in US dollars: balance, coupon
    balance, available balance, and the amount currently frozen by in-flight
    requests.
  version: 1.0.0
servers:
  - url: https://api.siray.ai
    description: Siray API Server
security: []
tags:
  - name: Account
    description: Inspect the account behind the authenticated API key.
paths:
  /v1/account/balance:
    get:
      tags:
        - Account
      summary: Get account balance
      description: >-
        Returns the identity of the account that owns the API key and its
        balance summary in US dollars. available_balance already excludes
        amounts frozen by in-flight requests, so it can be used directly as the
        spendable balance.
      operationId: get_account_balance
      responses:
        '200':
          description: Account identity and balance summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceResponse'
        '401':
          description: Missing or malformed credentials, or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key disabled or expired, or account forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Upstream billing validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    AccountBalanceResponse:
      type: object
      description: Account identity and balance summary response.
      required:
        - request_uuid
        - code
        - message
        - data
      properties:
        request_uuid:
          type: string
          description: Identifier of this API call, useful for support and log correlation.
        code:
          type: integer
          description: Service-level status code (200 on success).
          example: 200
        message:
          type: string
          description: Additional information about the request result.
          example: OK
        data:
          $ref: '#/components/schemas/AccountBalanceData'
      example:
        request_uuid: f1c2d3e4-5a6b-7c8d-9e0f-1a2b3c4d5e6f
        code: 200
        message: OK
        data:
          user_id: user-3f8a2c1d
          user_name: alice
          email: alice@example.com
          balance: 123.45
          coupon_balance: 1.25
          available_balance: 121.1
          frozen_balance: 3.6
    ErrorResponse:
      type: object
      description: Error envelope; no data field is returned on failure.
      required:
        - request_uuid
        - code
        - message
      properties:
        request_uuid:
          type: string
          description: Identifier of this API call.
        code:
          type: integer
          description: Service-level status code matching the HTTP status (401/403/500).
          example: 401
        message:
          type: string
          description: Human-readable failure description.
          example: missing authorization header
    AccountBalanceData:
      type: object
      description: >-
        Account identity and balance summary. All amounts are USD rounded to two
        decimal places.
      required:
        - user_id
        - user_name
        - email
        - balance
        - coupon_balance
        - available_balance
        - frozen_balance
      properties:
        user_id:
          type: string
          description: ID of the account that owns the API key.
        user_name:
          type: string
          description: Name of that account.
        email:
          type: string
          description: Email of that account.
        balance:
          type: number
          description: Account balance in USD.
          example: 123.45
        coupon_balance:
          type: number
          description: Remaining coupon balance in USD; expired coupons are excluded.
          example: 1.25
        available_balance:
          type: number
          description: 'Spendable balance in USD: balance + coupon_balance - frozen_balance.'
          example: 121.1
        frozen_balance:
          type: number
          description: >-
            Total amount currently reserved by in-flight requests, in USD; 0
            when nothing is frozen. Released automatically when requests settle
            or expire.
          example: 3.6
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token passed as a Bearer token in the Authorization header.

````