Usage & subscription

Read your plan, balance and month-to-date usage over the API.

GET /v1/usage

The numbers behind the meter, for the key you present: your plan and its limits, the live subscription window, this month's character count, and your remaining balance with its next expiry. It is the API version of the console's balance view — build your own gauge or alerting from it instead of scraping x-ratelimit-* response headers.

GET/v1/usage

Auth is your normal API key, either header convention (see Authentication). Limits attach to your organization, so every key in the workspace reads the same numbers.

curl https://api.kenpathlabs.com/v1/usage \
  -H "xi-api-key: $SVARA_API_KEY"

{
  "organisation_id": "9b805cde-4c1a-4b8e-9f0e-…",
  "mode": "lots",
  "plan": {
    "id": "growth",
    "name": "Growth",
    "monthly_characters": 1000000,
    "requests_per_minute": 200,
    "max_concurrent_streams": 10
  },
  "subscription": {
    "plan_id": "growth",
    "expires_at": "2026-09-18T09:14:00+00:00",
    "auto_renew": true,
    "renewal_plan_id": null,
    "falls_back_to": "free"
  },
  "month": {
    "period": "2026-08",
    "characters_used": 41230,
    "resets_at": "2026-09-01T00:00:00+00:00"
  },
  "balance": {
    "characters_remaining": 958770,
    "total_granted": 1000000,
    "next_expiry": { "at": "2026-10-17T09:14:00+00:00", "amount": 958770 },
    "lots": [
      {
        "kind": "plan_grant",
        "remaining": 958770,
        "expires_at": "2026-10-17T09:14:00+00:00"
      }
    ]
  }
}

Response fields

Parameter	Type	Default	Description
mode	string	-	How your balance is accounted: `lots` (prepaid character lots — the normal state), `wallet` or `allowance` (legacy accounting; the fields below degrade gracefully).
plan	object	-	Your tier and the limits admission enforces: monthly characters, requests per minute, concurrent streams. -1 means unlimited.
subscription	object \| null	-	The live window: which plan, when it ends, whether autopay renews it, and `falls_back_to` — the plan you revert to if it lapses.
month.characters_used	int	-	Characters metered this calendar month (UTC), across every key in the workspace. Only successful requests count.
month.resets_at	timestamp	-	First instant of next month, UTC — when the monthly counter starts over.
balance.characters_remaining	int	-	What you can spend right now. This is the same number admission checks.
balance.lots	array	-	Your balance by cohort — plan grants, top-ups (`purchase`), promos — each with its own expiry. Whatever expires soonest is spent first.
balance.next_expiry	object \| null	-	The soonest cohort death: when, and how many characters go with it.

Poll politely: these numbers move only when you synthesize, so once a minute is plenty for a dashboard. The endpoint is not rate-limit exempt — a tight loop spends your requests-per-minute budget.

ElevenLabs dialect

If you are using the ElevenLabs SDK against Svara (see SDKs & compatibility), its subscription call works unchanged:

GET/v1/user/subscription

{
  "tier": "growth",
  "status": "active",
  "character_count": 41230,
  "character_limit": 1000000,
  "can_extend_character_limit": false,
  "allowed_to_extend_character_limit": false,
  "next_character_count_reset_unix": 1760691240,
  "billing_period": "monthly_period",
  "character_refresh_period": "monthly_period",
  "currency": "inr"
}

character_count and character_limit are cycle-shaped the way that SDK expects: consumed versus granted across your live cohorts, with next_character_count_reset_unix set to the soonest expiry. For the richer per-cohort picture, prefer /v1/usage.