Organization billing API

Use these endpoints to show an organization's balance and usage in your own dashboard or finance tooling. They authenticate with an organization billing token, not with a qf_... API key. The token can only read; it cannot call models, change keys, or move money.

Get a token

An organization owner or administrator creates the token in the Quotaflow console under Settings → Billing → Organization billing API. The full token (prefix qf_org_billing_) is shown once, when it is created; store it on your server, never in browser code. Each organization has at most one active token. Rotate token replaces it and the previous token stops working immediately; Revoke token disables it. The token does not expire on its own.

Send it as a bearer token, or in the X-Organization-Billing-Token header:

Authorization: Bearer qf_org_billing_your_token_here

Balance

GET https://api.quotaflow.ai/api/v1/organization/billing/balance

{
  "code": 0,
  "message": "success",
  "data": {
    "organization_id": 42,
    "balance_usd": 60,
    "reserved_usd": 5.25,
    "available_usd": 54.75,
    "status": "reconciled"
  }
}

balance_usd is the book balance, reserved_usd is held for admitted requests that have not settled, and available_usd is what can be spent now. An organization wallet that is missing or not yet reconciled returns 503 with reason ORG_BALANCE_RECONCILIATION_REQUIRED; it is never reported as a zero balance.

Daily usage

GET https://api.quotaflow.ai/api/v1/organization/billing/usage/daily?date=YYYY-MM-DD

Returns usage for one UTC day, from date 00:00:00Z up to (not including) the next day's 00:00:00Z. date defaults to today (UTC). Request one day per call; for a longer period, call once per day.

The data object carries organization_id, from, to, totals (requests, input/output/cache tokens, cost_usd, actual_cost_usd, usage_cost_usd), breakdowns by projects, api_keys, models, and workflows, unavailable_dimensions for any breakdown that cannot be computed, wallet_spend (what the wallet actually paid in the window), and usage_coverage. Usage figures are usage facts; wallet_spend is the money that was debited.

Errors

A 5xx other than the one above is a server-side failure; retry later. It never means the token was revoked.