Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
API ReferenceBilling and usageBilling

Org balance + recent transactions

Returns the org's ledger and available balances, accrued and current-month usage, monthly spend limit, minimum deposit, and up to 25 of its newest transactions. Provider payouts are left out of the transactions.

Required permission

Requires the usage.read permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

Guided workflow: orl balance

orl balance
orl billing balance get
GET
/v1/orgs/{orgId}/billing/balance

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

orgId*string

Response Body

Balance

application/json
  1. response
balanceCents*integer

Raw ledger balance (deposits + credits − settled debits).

availableCents*integer

Spendable balance = balanceCents − accruedUsageCents. This is what every control-plane billing gate checks. It includes pending compute and inference usage, can be below balanceCents while usage is running, and can be slightly negative between auto-recharge ticks.

accruedUsageCents*integer

Usage cost not yet settled into a transaction: current-month compute, pending inference, plus any recently ended compute month whose settlement debit has not been written yet. This is the amount netted from balanceCents to produce availableCents.

currentMonthUsageCents*integer

Total compute plus inference usage in the current UTC calendar month, including inference already drained into the ledger and the live pending inference accrual. Use this for "spend this month" displays; use accruedUsageCents for balance math.

currentMonthComputeCents*integer

Compute usage accrued in the current UTC calendar month.

currentMonthInferenceCents*integer

Inference usage in the current UTC calendar month: settled whole-cent inference debits plus whole pending inference cents. A fractional pending cent is intentionally omitted instead of inflating displayed spend.

pendingInferenceCents*integer

Whole inference cents not yet drained into the ledger. Fractional cents remain in nanoUSD in the accrual and are omitted from this integer display value.

pendingInferenceReservedCents*integer

Pending inference reserved by balance enforcement, rounded up to the next cent. This can be one cent higher than pendingInferenceCents.

priorUnsettledComputeCents*integer

Compute usage from recently ended months that is marked billable but whose settlement transaction has not been written yet.

monthlySpendLimitCents?integer

The org's monthly spend cap, or null if no limit is set. Drives the "used of limit" budget gauge in the dashboard.

minDepositCents?integer

Smallest deposit the org can make right now, in cents: the flat $25 floor, raised to one hour of usage at the current burn while the org has open usage running, clamped to the org's per-deposit cap. This is the exact minimum the deposit endpoint enforces (INSUFFICIENT_RUNWAY on a lower amount), so clients should render it rather than re-derive it.

transactions*array<>
Example Request
curl -X GET 'https://api.openrelay.inc/v1/orgs/string/billing/balance'
Example Response
{  "balanceCents": 12550,  "availableCents": 10430,  "accruedUsageCents": 2120,  "currentMonthUsageCents": 2120,  "currentMonthComputeCents": 2000,  "currentMonthInferenceCents": 120,  "pendingInferenceCents": 20,  "pendingInferenceReservedCents": 20,  "priorUnsettledComputeCents": 0,  "monthlySpendLimitCents": null,  "transactions": [    {      "id": "txn_01hzy3",      "type": "stripe_deposit",      "source": "stripe",      "amountCents": 10000,      "description": "Card deposit",      "createdAt": "2026-06-28T14:03:22Z"    }  ]}