Instagram

Docs

Usage

Retrieve current-period usage and token counts for your organization, plus your own credit balance.

Returns what your organization has spent this billing period, how many tokens that came to, and what credit you have left. Use it to surface spend inside your own dashboard, or to alert before a balance runs dry.

Two scopes in one response. usage and limits describe the organization named by X-Organization-Id. credits describes the authenticated user — credit belongs to a person, not to an organization, and follows them between organizations. The organization header does not select the wallet.

Endpoint

GET https://api.elyxir.ai/api/v1/usage

Authentication

This is a Platform API endpoint — OAuth JWT plus organization header, not an elyxir_ key.

Header	Required	Description
`Authorization`	Yes	`Bearer <oauth-jwt>`
`X-Organization-Id`	Yes	Your organization UUID

Example

curl https://api.elyxir.ai/api/v1/usage \
  -H "Authorization: Bearer <oauth-jwt>" \
  -H "X-Organization-Id: 00000000-0000-0000-0000-000000000000"

Response

{
  "organization": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "standard"
  },
  "currentPeriod": {
    "start": "2026-08-01T00:00:00.000Z",
    "end": "2026-09-01T00:00:00.000Z"
  },
  "usage": {
    "totalCost": "12.45",
    "totalTokens": 2450000,
    "promptTokens": 1800000,
    "completionTokens": 650000
  },
  "limits": {
    "inferenceTokensLimit": 5000000
  },
  "credits": {
    "scope": "user",
    "userId": "11111111-1111-1111-1111-111111111111",
    "currentBalance": 37.55,
    "spendableMicros": 37550000,
    "netMicros": 37550000,
    "unallocatedDebtMicros": 0,
    "lotOverdrawMicros": 0,
    "openLots": 2,
    "nextExpiresAt": "2027-01-14T00:00:00.000Z"
  }
}

Fields

Field	Description
`organization.plan`	Current plan code
`currentPeriod`	The billing window these figures cover
`usage.totalCost`	Spend this period, in USD, as a string
`usage.totalTokens`	Prompt plus completion tokens
`limits`	Ceilings that apply on this plan. Additional keys may appear here over time — read the ones you need rather than assuming the shape is fixed
`credits.scope`	Always `"user"`. The credit block describes the authenticated caller, not the organization
`credits.userId`	The user whose wallet these figures belong to
`credits.currentBalance`	Spendable credit in USD, rounded to cents and never negative. Display only
`credits.spendableMicros`	The same figure in integer micro-USD (1 USD = 1,000,000), floored at zero
`credits.netMicros`	Spendable credit minus outstanding debt, in micro-USD, not floored — this one can be negative. Test this, not `currentBalance`, when deciding whether an account can spend
`credits.unallocatedDebtMicros`	Usage charged against no credit at all, in micro-USD. Zero for most accounts
`credits.lotOverdrawMicros`	Usage that drew a credit amount past empty, in micro-USD. Zero for most accounts
`credits.openLots`	How many unexpired credit lots remain
`credits.nextExpiresAt`	When the soonest-expiring lot dies, or `null` if nothing on the account expires

totalCost is a string, not a number — it carries exact decimal precision. Parse it as a decimal rather than a float if you're doing arithmetic on it.

Compare micros, display dollars. currentBalance is rounded to cents, so testing it against a threshold decides sub-cent cases by the rounding rather than by the ledger — which is exactly the case that matters on the first request after a top-up. Use netMicros for any decision.

Credit expires now

Credit is held in lots, each of which dies on a fixed date (six months from purchase by default). An account that spends nothing can still reach a zero balance. openLots and nextExpiresAt are there so you can warn before that happens; a balance that drops with no matching usage is expiry, not an error.

Removed fields

credits.totalPurchased and credits.totalSpent were removed when credit moved to the per-user ledger. They reported an organization's lifetime purchased-versus-spent pair, and the ledger no longer keeps such a pair for anyone — it tracks live lots, debt and overdraw. There is no replacement, and nothing in the new response should be summed to reconstruct them: a lot total is current credit, not lifetime purchases. For lifetime history, record snapshots yourself or use the cost dashboard.

Errors

Status	Meaning
401	Invalid or expired JWT
403	Not a member of this organization
502	The credit ledger could not be read (`code: "balance_service_unavailable"`). Retry — this is never reported as a zero balance

Notes

Figures cover the current billing period and reset when it rolls over. If you need a longer history, record snapshots yourself — or use the cost dashboard in Studio, which retains history and breaks spend down by model and project.

API keys — provisioning keys programmatically
Credits — topping up the balance
Cost dashboard — spend over time in Studio

API Keys Error Handling