Balance

The balance endpoint returns your weekly allowance balance, top-up credits, plan cap, and reset schedule. Call it any time to check how many credits you have left. For an overview of allowances and top-up credits, 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, weekly cap, and reset schedule.

{
  "object": "balance",
  "available": true,
  "plan": "lite",
  "balances": {
    "weekly": { "credits": 28000000, "percent": 70 },
    "additional": { "credits": 0 },
    "total": { "credits": 28000000 }
  },
  "caps": { "weekly": { "credits": 40000000 } },
  "refresh": { "cadence": "weekly", "day": "friday", "time": "06:00Z" }
}

string

Always "balance".

boolean

true while balances.weekly.credits + balances.additional.credits is greater than zero. Otherwise, false.

string

Your current Kyara plan identifier. Spark returns "lite". Ember returns "premium".

object

Your remaining credits broken down by type.

Show Balances object

object

Credits remaining in your weekly allowance. Contains credits (integer) and percent (number). The credit balance can be negative when a completed request goes over the allowance. percent is the remaining balance as a percentage of the weekly cap, clamped from 0 to 100.

object

Purchased top-up credits. Contains credits (integer) only. Top-up credits have no plan cap and never go negative.

object

Weekly allowance credits plus top-up credits. Contains credits (integer) only. A negative weekly balance reduces this total.

object

The weekly credit limit for your plan.

Show Caps object

object

Maximum weekly allowance credits. Contains credits (integer).

object

The global weekly reset schedule. This object contains static schedule configuration, not per-user billing-window state. Every account resets at the same moment.

Show Refresh object

string

Always "weekly".

string

Always "friday".

string

Always "06:00Z", which is 06:00 UTC.

Errors

Errors follow the standard OpenAI error format:

401 invalid_api_key: your API key is missing or not recognized. A malformed Authorization header returns 400 instead. See Authentication.
500 server_error: the key is valid but no balance could be read. This also happens when the account has no active subscription.

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. Reading your balance does not trigger a refill.

Get Started

Integrations

API Reference

Reference

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors