Balance

The balance endpoint returns your current credit balances, plan caps, and billing window. Call it any time to check how many credits you have left and when your base balance next refreshes. For how the buckets and credit system work, see Plans and credits.

Request

GET https://api.kyara-intelligence.com/v1/balance

curl

curl https://api.kyara-intelligence.com/v1/balance \
  -H "Authorization: Bearer $KYARA_INTELLIGENCE_API_KEY"

string

required

Your Kyara Intelligence API key, formatted as Bearer YOUR_API_KEY.

Response

A successful request returns a JSON object with your balances, caps, and the active billing window.

{
  "object": "balance",
  "available": true,
  "plan": "lite",
  "balances": {
    "base": { "credits": 500000, "percent": 50 },
    "overage": { "credits": 10000000, "percent": 25 },
    "additional": { "credits": 0 },
    "total": { "credits": 10500000, "percent": 25.61 }
  },
  "caps": {
    "base": { "credits": 1000000 },
    "overage": { "credits": 40000000 },
    "total": { "credits": 41000000 }
  },
  "baseWindow": {
    "startedAt": "2030-01-01T00:00:00.000Z",
    "refreshesAt": "2030-01-01T08:00:00.000Z"
  },
  "overageWindow": {
    "startedAt": "2030-01-01T00:00:00.000Z",
    "refreshesAt": "2030-01-08T00:00:00.000Z"
  }
}

string

Always "balance".

boolean

true while you have credits remaining. Becomes false when your total balance is fully exhausted.

string

Your current Kyara plan identifier (e.g. "lite").

object

Your remaining credits broken down by type.

Show Balances object

object

Credits from your plan’s base allocation. Contains credits (integer) and percent (number, the percentage of the base cap remaining).

object

Credits from your overage pool. Contains credits (integer) and percent (number).

object

Purchased credits, which have no plan cap. Contains credits (integer) only, with no percent.

object

Combined base, overage, and additional credits. Contains credits (integer) and percent (number, the percentage of the total cap remaining). The percent is measured against the base and overage caps only, since additional credits are uncapped.

object

The maximum credit limits for your plan.

Show Caps object

object

Maximum base credits. Contains credits (integer).

object

Maximum overage credits. Contains credits (integer).

object

Maximum total credits (base.credits + overage.credits). Contains credits (integer).

object

The current billing window for your base credit allocation.

Show BaseWindow object

string

ISO 8601 timestamp when the current billing window began.

string

ISO 8601 timestamp when your base credits will next refresh.

object

The current billing window for your overage credit allocation.

Show OverageWindow object

string

ISO 8601 timestamp when the current overage window began.

string

ISO 8601 timestamp when your overage credits will next refresh.

Errors

Errors follow the standard OpenAI error format:

401 authentication_error: your API key is missing, malformed, or invalid.
500 server_error: the key is valid but Kyara hit missing or invalid balance data.

This endpoint never blocks on an empty balance. It always reports the current state and returns available: false when credits are exhausted rather than refusing the request.

Get Started

Integrations

API Reference

Reference

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors