Skip to content
FLORA FLORA API

Get workspace balance and usage

GET
/workspaces/{workspaceId}/usage
 
import { FloraClient } from '@flora-ai/flora';


const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });


const workspace = await client.workspaces.getUsage({
  workspaceId: '<workspaceId>',
});
console.log(workspace);

Returns, in USD, the balance the credential’s user may see in a workspace and, when they may see workspace usage, what the workspace was charged over an inclusive UTC day range (default: the last 30 days; at most 31 days, ending no later than today). On a plan that includes usage reporting, a user with billing permissions for the workspace gets the workspace balance and workspace totals (balance_scope workspace). Anyone else gets only their own allowance and any member limit on them (balance_scope caller), and spend is unavailable with reason entitlement_missing (the plan lacks usage reporting) or permission_missing (the user lacks billing permissions), never zero. available_cost is current, not limited to the period, and does not guarantee that a run will be admitted. Totals only: no pool breakdown and no per-member, per-model, or per-run detail. An API key needs billing permission on the workspace; an OAuth token works for any workspace its user is a member of. Other workspaces return 403.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
workspaceId
required

Workspace identifier

string
/^ws_\S+$/

Workspace identifier

Query Parameters

Section titled “Query Parameters ”
start_date

First UTC day to include (YYYY-MM-DD), at most 30 days before end_date. Defaults to 29 days before end_date.

string
/^\d{4}-\d{2}-\d{2}$/

First UTC day to include (YYYY-MM-DD), at most 30 days before end_date. Defaults to 29 days before end_date.

end_date

Last UTC day to include (YYYY-MM-DD), no later than today. Defaults to today (UTC).

string
/^\d{4}-\d{2}-\d{2}$/

Last UTC day to include (YYYY-MM-DD), no later than today. Defaults to today (UTC).

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Workspace usage returned.

Media type application/json
object
workspace_id
required

Workspace identifier

string
/^ws_\S+$/
currency
required

Currency of every cost in this response

Allowed value: USD
balance_scope
required

Whose balance available_cost is, decided by the workspace’s plan and the current role of the credential’s user. workspace: the plan includes usage reporting and the user holds billing permissions for the workspace, directly or through an organization role. caller: anyone else, including billing admins on a plan without usage reporting.

string
Allowed values: caller workspace
available_cost
required

USD that can still be spent now, read at request time and not limited to any period. For balance_scope workspace: what the credit pool the workspace draws from can still fund (included, prepaid, and remaining enabled overage usage), before any per-member limit; an organization’s workspaces may share that pool. For balance_scope caller: the credential’s user’s own allowance from that pool, held to any spending limit or cap on that user, so it equals the pool’s amount when none applies. Workspace-level spending caps are not reflected, and it does not guarantee that a run will be admitted: other spend and concurrent runs change it.

number
member_limit

The member spending limit that binds the credential’s user, set on their workspace or organization membership, whichever leaves less room. Present only for balance_scope caller, and only when such a limit is set.

object
limit_cost
required

The limit in USD

number
period
required

Month: the limit resets each monthly usage cycle. all_time: it never resets.

string
Allowed values: month all_time
spend
required
Any of:
object
status
required
Allowed value: available
scope
required

The totals cover every run charged in the workspace, by any member or agent.

Allowed value: workspace
period
required

Inclusive UTC day range the totals cover

object
start_date
required

UTC calendar day in YYYY-MM-DD form

string
/^\d{4}-\d{2}-\d{2}$/
end_date
required

UTC calendar day in YYYY-MM-DD form

string
/^\d{4}-\d{2}-\d{2}$/
total_cost
required

USD charged in the workspace in the period; the same figure as the in-app Usage tab for the same range.

number
classified_runs
required

Sum of the classified run categories in runs_by_category. Spend on runs whose output modality cannot be classified appears only in total_cost.

integer
runs_by_category
required

Charged runs in the period, by classified output modality. Runs whose modality cannot be classified are not counted.

object
text
required

Text generation runs

integer
image
required

Image generation runs

integer
video
required

Video generation runs

integer
audio
required

Audio generation runs

integer
technique
required

Technique runs

integer
Example 
{
  "workspace_id": "ws_abc123",
  "currency": "USD",
  "balance_scope": "caller",
  "member_limit": {
    "period": "month"
  },
  "spend": {
    "status": "available",
    "scope": "workspace",
    "period": {
      "start_date": "2026-08-01",
      "end_date": "2026-08-01"
    }
  }
}