Skip to content
FLORA FLORA API

Get organization usage

GET
/organizations/{organizationId}/usage
 
import { FloraClient } from '@flora-ai/flora';


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


const organization = await client.organizations.getUsage({
  organizationId: '<organizationId>',
});
console.log(organization);

Returns usage charged across every workspace in an organization for an inclusive UTC day range (default: the last 30 days), as USD totals and run counts. Pass group_by to add one breakdown: per workspace, per member, per model, or per day. The figures come from the same aggregates as the in-app Organization Analytics tab; for per-generation detail with project and user columns, create a usage export instead. Requires an organization with multiple workspaces enabled, and the credential’s user must hold billing permissions in that organization. An API key works for the organization that owns its workspace; an OAuth token works for any organization the user administers. Other organizations return 403.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
organizationId
required

Organization identifier

string
/^org_\S+$/

Organization identifier

Query Parameters

Section titled “Query Parameters ”
start_date

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

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

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

end_date

Last UTC day to include (YYYY-MM-DD). Defaults to today (UTC).

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

Last UTC day to include (YYYY-MM-DD). Defaults to today (UTC).

group_by

Breakdown axis. workspace: one row per organization workspace. user: one row per member (plus agent-attributed pool spend). model: one row per model endpoint, with all technique runs combined under model_id technique. day: one row per UTC day.

string
Allowed values: workspace user model day

Breakdown axis. workspace: one row per organization workspace. user: one row per member (plus agent-attributed pool spend). model: one row per model endpoint, with all technique runs combined under model_id technique. day: one row per UTC day.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Organization usage returned.

Media type application/json
object
organization_id
required

Organization identifier

string
/^org_\S+$/
period
required

Inclusive UTC day range the figures 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

Usage charged across the organization in USD, derived from the same per-day aggregate as the Organization Analytics tab. Breakdown rows and CSV exports sum exact per-charge amounts, so their totals can differ from this figure by rounding, well under 0.1%.

number
total_runs
required

Charged runs across the organization

integer
runs_by_category
required

Charged runs split by output modality

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
unknown
required

Runs whose modality could not be classified. Includes technique runs recorded before technique became its own category, which the in-app analytics count the same way.

integer
workspaces
required

Every active workspace in the organization; the totals cover all of them

Array<object>
object
workspace_id
required

Workspace identifier

string
/^ws_\S+$/
name
required

Workspace name

string
group_by
required
Any of:

Breakdown axis. workspace: one row per organization workspace. user: one row per member (plus agent-attributed pool spend). model: one row per model endpoint, with all technique runs combined under model_id technique. day: one row per UTC day.

string
Allowed values: workspace user model day
by_workspace

Per-workspace rows, highest cost first. Present when group_by is workspace.

Array<object>
object
workspace_id
required

Workspace identifier

string
/^ws_\S+$/
name
required

Workspace name

string
cost
required

Usage charged in USD

number
runs
required

Charged runs

integer
by_user

Per-member rows summed across every workspace, highest cost first. Present when group_by is user. Covers people who currently hold a membership in one of the workspaces; spend by members since removed stays in the totals but is not itemized here — use a usage export for that.

Array<object>
object
kind
required

Member: a person with a workspace membership. agent: workspace-pool spend attributed to an agent (for example the FLORA agent) rather than to a member.

string
Allowed values: member agent
email
required
Any of:
string
name
required

Display name

string
cost
required

Usage charged in USD

number
by_model

Per-model rows summed across workspaces, highest cost first. Present when group_by is model. Rows cover the live and static model catalogs; spend on endpoints retired from both is reported in unattributed_cost.

Array<object>
object
model_id
required

Model endpoint ID, or technique for every technique run combined

string
category
required

Output modality of the model

string
Allowed values: text image video audio technique unknown
cost
required

Usage charged in USD

number
runs
required

Charged runs

integer
unattributed_cost

With group_by=model: USD charged in the covered workspaces that no model row accounts for. Mostly endpoints no longer in any catalog; a small residue can also come from rounding between the per-day and per-model aggregates. Zero when every row was readable. Present when group_by is model.

number
by_day

One row per UTC day in the period, oldest first. Present when group_by is day.

Array<object>
object
date
required

UTC calendar day in YYYY-MM-DD form

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

Usage charged in USD

number
runs
required

Charged runs

integer
coverage

Present only when a model breakdown covered the top workspaces by cost rather than all of them; totals still cover every workspace.

object
workspaces_included
required

Workspaces the model breakdown was read from

integer
workspaces_total
required

Active workspaces in the organization

integer
Example 
{
  "organization_id": "org_abc123",
  "period": {
    "start_date": "2026-08-01",
    "end_date": "2026-08-01"
  },
  "workspaces": [
    {
      "workspace_id": "ws_abc123"
    }
  ],
  "group_by": "workspace",
  "by_workspace": [
    {
      "workspace_id": "ws_abc123"
    }
  ],
  "by_user": [
    {
      "kind": "member"
    }
  ],
  "by_model": [
    {
      "model_id": "t2i-flux-2-pro",
      "category": "text"
    }
  ],
  "by_day": [
    {
      "date": "2026-08-01"
    }
  ]
}