Early access: features, availability, and pricing may change as Kyara Intelligence evolves.

API reference

Balance

Read your weekly allowance, top-up credits, weekly cap, reset schedule and subscription.

The balance endpoint returns what you have left to spend. Call it as often as you like: it never blocks on an empty balance, and reading it doesn't change anything. For how the allowance and top-up credits work, see Plans and credits.

Request

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

Authenticate with your API key, or with an OAuth access token to read a linked user's balance. See Authentication.

Response

{
  "object": "balance",
  "available": true,
  "plan": "lite",
  "balances": {
    "weekly": { "credits": 28000000, "percent": 70 },
    "additional": { "credits": 50000000 },
    "total": { "credits": 78000000 }
  },
  "caps": { "weekly": { "credits": 40000000 } },
  "refresh": { "cadence": "weekly", "day": "friday", "time": "06:00Z" },
  "account": {
    "user_id": "8fJ2kQvN1xTzR6mWcY0bLa3s",
    "plan": "lite",
    "plan_status": "active",
    "period_end": "2026-11-25T09:30:00.000Z"
  }
}

All amounts are in credits: 10,000,000 credits are $1.00.

object string

Always "balance".

available boolean

true while balances.total.credits is above zero, otherwise false.

plan string or null

Your plan ID: "lite" for Spark, "premium" for Ember, or null without an active subscription. It is active-only because the weekly numbers depend on it. For the plan whatever its status, read account.plan.

balances.weekly.credits integer

What is left of your weekly allowance. It can be negative after a request that cost more than you had left; the shortfall comes off the next Friday reset.

balances.weekly.percent number

The weekly balance as a percentage of your weekly cap, clamped between 0 and 100. Always 0 without a plan.

balances.additional.credits integer

Your top-up credits. They have no cap and never go negative.

balances.total.credits integer

What you can spend: weekly balance plus top-up credits, so a negative weekly balance lowers it. Without an active plan, the weekly allowance is paused and this is your top-up credits alone.

caps.weekly.credits integer

Your plan's weekly allowance. 0 without a plan.

refresh object

The reset schedule: cadence is always "weekly", day always "friday", and time always "06:00Z" (06:00 UTC). It is the same for every account, not a per-account billing window.

account.user_id string

The Kyara user ID of the account the token belongs to.

account.plan string or null

The subscription's plan ID, reported whatever its status, or null without a subscription.

account.plan_status string

The subscription status, such as active, trialing, past_due, unpaid or canceled; none without a subscription.

account.period_end string or null

When the current billing period ends, as an ISO 8601 timestamp, or null. Always null without a subscription.

Without an active plan

When your subscription has ended or a payment failed, the endpoint still answers. plan is null, the weekly cap is 0, and total counts only your top-up credits, since those are all you can spend until the plan is back. account still names the subscription. Here, a payment for an Ember plan failed:

{
  "object": "balance",
  "available": true,
  "plan": null,
  "balances": {
    "weekly": { "credits": 12000000, "percent": 0 },
    "additional": { "credits": 50000000 },
    "total": { "credits": 50000000 }
  },
  "caps": { "weekly": { "credits": 0 } },
  "refresh": { "cadence": "weekly", "day": "friday", "time": "06:00Z" },
  "account": {
    "user_id": "8fJ2kQvN1xTzR6mWcY0bLa3s",
    "plan": "premium",
    "plan_status": "past_due",
    "period_end": "2026-11-20T06:00:00.000Z"
  }
}

The account field

account reports the same subscription facts as the OAuth token response, for API keys and OAuth access tokens alike. If the account has several subscriptions, it describes an active or trialing one first, then a past_due or unpaid one, then the one with the latest period end.

The top-level plan is set only while the subscription is active or trialing, because the weekly numbers depend on it. account.plan is reported whatever the status, so a past_due user has top-level plan: null and account.plan: "premium". Read plan to interpret the weekly numbers, and account to see what the user subscribes to, for example to ask them to fix a failed payment.

Subscriptionplanaccount.planaccount.plan_status
Ember, paid"premium""premium""active"
Ember, payment failednull"premium""past_due"
No subscriptionnullnull"none"

account doesn't include the user's email. An app that needs it uses the OAuth email scope.

Errors

  • 401 invalid_api_key: the token is missing or not recognized. A malformed Authorization header returns 400 instead.
  • 500: your balance couldn't be read. Retry, and contact us if it persists.
  • 503 service_unavailable: the token or the subscription couldn't be checked right now. Retry with backoff.