> ## Documentation Index > Fetch the complete documentation index at: https://docs.naga.ac/llms.txt > Use this file to discover all available pages before exploring further. # Get the account balance > Returns the account's credit balance. The response carries a single key, `balance`, holding the credits the account has left. Requires a provisioning key. `balance` crosses the wire as a decimal string, `"12.3456789012"` rather than `12.3456789012`. Credits are a decimal quantity, and a JSON number would round them in a client that parses numbers as binary floats. Parse the value with a decimal type, and serialize it back as a string. The balance governs access to paid models. A request for a paid model is admitted while the balance is above zero. At zero or below, `/v1/models` lists only the free models to that account. Free models do not consult the balance. A per-key spending cap is separate and does not appear here. Each API key may carry its own `credit_limit`, reported by `/v1/account/keys`, bounding what that key may spend out of this balance. Every response below `200` carries an object under `error` with a machine-readable `type` and a human-readable `message`. Three statuses reach this operation, and it has no rate limit. * `401` — the provisioning key is missing, unknown, or disabled. An ordinary API key returns the same status. * `500` — a failure of the gateway itself. * `503` — a store this operation depends on did not answer. `Retry-After` carries the seconds to wait. ## OpenAPI ````yaml /openapi/naga-api.json get /v1/account/balance openapi: 3.1.0 info: title: NagaAI API description: >- Naga routes inference requests to a pool of upstream providers behind one endpoint. Requests are written in the OpenAI or the Anthropic dialect, and the gateway selects a provider that serves the requested model. Two credentials exist and they are not interchangeable. An API key reaches models. A provisioning key manages the account: its keys, its balance, and its usage. Each operation declares which one it accepts. Accounts are charged for the tokens a request consumes, at the published price of the model that served it. termsOfService: https://naga.ac/legal/terms contact: name: NagaAI url: https://naga.ac version: '2026-03-31' summary: Unified AI API with OpenAI and Anthropic compatibility layers. servers: - url: https://api.naga.ac description: Production - url: http://localhost:8500 description: Local development security: [] tags: - name: Chat Completions description: >- OpenAI-compatible chat completion requests, including streaming, tools, and multimodal input. - name: Messages description: >- Anthropic-compatible Messages API requests used by Claude-style clients and agents. - name: Responses description: >- OpenAI-compatible Responses API requests for structured input, tools, and streaming output items. - name: Embeddings description: >- Create vector embeddings for search, retrieval, clustering, and ranking use cases. - name: Images description: >- Generate or edit images with multimodal models and OpenAI-compatible payloads. - name: Audio description: >- Generate speech or convert uploaded audio into transcriptions and translations. - name: Moderations description: Classify text and image inputs for safety policy categories. - name: Models description: List available models, capabilities, and pricing metadata. - name: Startups description: >- Public metadata about AI startups and model providers surfaced by the gateway. - name: Account description: Provisioning-key protected account balance and usage endpoints. - name: API Keys description: Provisioning-key protected API key management endpoints. paths: /v1/account/balance: get: tags: - Account summary: Get the account balance description: > Returns the account's credit balance. The response carries a single key, `balance`, holding the credits the account has left. Requires a provisioning key. `balance` crosses the wire as a decimal string, `"12.3456789012"` rather than `12.3456789012`. Credits are a decimal quantity, and a JSON number would round them in a client that parses numbers as binary floats. Parse the value with a decimal type, and serialize it back as a string. The balance governs access to paid models. A request for a paid model is admitted while the balance is above zero. At zero or below, `/v1/models` lists only the free models to that account. Free models do not consult the balance. A per-key spending cap is separate and does not appear here. Each API key may carry its own `credit_limit`, reported by `/v1/account/keys`, bounding what that key may spend out of this balance. Every response below `200` carries an object under `error` with a machine-readable `type` and a human-readable `message`. Three statuses reach this operation, and it has no rate limit. * `401` — the provisioning key is missing, unknown, or disabled. An ordinary API key returns the same status. * `500` — a failure of the gateway itself. * `503` — a store this operation depends on did not answer. `Retry-After` carries the seconds to wait. operationId: get_account_balance responses: '200': description: The account's credit balance, as a decimal string. content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' examples: basic: summary: The balance, as a decimal string value: balance: '12.4750' '401': description: |- The provisioning key is missing, malformed, or does not belong to an account. An ordinary API key is refused here too: that key reaches models, and these routes manage the account itself. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid-provisioning-key: summary: >- 401 — this route wants the provisioning key, not an inference key value: error: type: invalid_request_error message: Invalid provisioning key. '500': description: |- The gateway failed for a reason of its own. Report it — this status is reserved for Naga's own bugs. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: |- A store the gateway needs to answer this did not respond. `Retry-After` carries the suggested wait. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - provisioningBearerAuth: [] x-codeSamples: - lang: bash label: curl source: |- curl https://api.naga.ac/v1/account/balance \ -H "Authorization: Bearer $NAGA_PROVISIONING_KEY" components: schemas: BalanceResponse: type: object description: The body of `GET /v1/account/balance`. required: - balance properties: balance: type: string description: >- The account's credit balance, as a decimal STRING — a JSON number would round it. A request for a paid model is admitted only while this is above zero; free models do not consult it. ErrorEnvelope: type: object description: |- `{"error": {…}}` — the body of every non-2xx answer outside `/v1/messages`. required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: >- The failure itself, and the envelope's only member. Every non-2xx HTTP status arrives with it, and a 2xx answer never does. ErrorBody: type: object description: |- The `error` member: what went wrong, in the caller's terms. `code` and `param` are optional AND nullable, and both halves are load bearing: the boundary omits them, the LLM dialect writes them as `null`. A schema that only allowed one of the two would contradict a body the gateway actually sends. required: - type - message properties: type: type: string description: >- The machine-readable class of the failure, for example `invalid_request_error` or `server_error`. message: type: string description: The human-readable sentence shown to the caller. code: type: - string - 'null' description: The finer-grained code, when the failure has one. param: type: - string - 'null' description: The request field the failure is about, when it is about one. securitySchemes: provisioningBearerAuth: type: http scheme: bearer description: >- An account provisioning key. Send it as `Authorization: Bearer `. Provisioning keys manage the account and cannot reach a model. ````