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.
| Subscription | plan | account.plan | account.plan_status |
|---|---|---|---|
| Ember, paid | "premium" | "premium" | "active" |
| Ember, payment failed | null | "premium" | "past_due" |
| No subscription | null | null | "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 malformedAuthorizationheader returns400instead.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.