--- title: "Get workspace balance and usage" method: GET path: "/workspaces/{workspaceId}/usage" tags: ["Workspaces"] --- # Get workspace balance and usage `GET /workspaces/{workspaceId}/usage` ## Request - Base URL: `https://app.flora.ai/api/v1` - URL: `https://app.flora.ai/api/v1/workspaces/{workspaceId}/usage` - Auth: HTTP bearer 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. ## Path parameters - `workspaceId` string, required: Workspace identifier ## Query parameters - `start_date` string: First UTC day to include (YYYY-MM-DD), at most 30 days before end_date. Defaults to 29 days before end_date. - `end_date` string: Last UTC day to include (YYYY-MM-DD), no later than today. Defaults to today (UTC). ## Response `200` Workspace usage returned. - object - `workspace_id` string, required: Workspace identifier - `currency` 'USD', required: Currency of every cost in this response - `balance_scope` 'caller' | 'workspace', 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. - `available_cost` number, 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. - `member_limit` object: 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. - `limit_cost` number, required: The limit in USD - `period` 'month' | 'all_time', required: month: the limit resets each monthly usage cycle. all_time: it never resets. - `spend` union, required: Workspace totals over the requested range, given only to a balance_scope workspace caller. When status is unavailable, reason says why, and no totals or period are given. - object - `status` 'available', required - `scope` 'workspace', required: The totals cover every run charged in the workspace, by any member or agent. - `period` object, required: Inclusive UTC day range the totals cover - `start_date` string, required: UTC calendar day in YYYY-MM-DD form - `end_date` string, required: UTC calendar day in YYYY-MM-DD form - `total_cost` number, required: USD charged in the workspace in the period; the same figure as the in-app Usage tab for the same range. - `classified_runs` integer, 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. - `runs_by_category` object, required: Charged runs in the period, by classified output modality. Runs whose modality cannot be classified are not counted. - `text` integer, required: Text generation runs - `image` integer, required: Image generation runs - `video` integer, required: Video generation runs - `audio` integer, required: Audio generation runs - `technique` integer, required: Technique runs - object - `status` 'unavailable', required - `reason` 'entitlement_missing' | 'permission_missing' | 'summary_unavailable', required: entitlement_missing: the workspace's plan does not include usage reporting. permission_missing: the plan includes it, but the credential's user holds no billing permissions for the workspace. summary_unavailable: the totals could not be computed; retry, or request a shorter range. ## Other responses - `400`: 400 - `401`: 401 - `402`: 402 - `403`: 403 - `404`: 404 - `409`: 409 - `429`: 429 - `500`: 500 - `503`: 503 ## Changes - **2026-10-28** `a8351619f225`: 9 warning - added the new `not_configured` enum value to the `error/code` response property for the response status `400` - added the new `not_configured` enum value to the `error/code` response property for the response status `401` - added the new `not_configured` enum value to the `error/code` response property for the response status `402` - added the new `not_configured` enum value to the `error/code` response property for the response status `403` - …5 more - **2026-10-16** `e54130373b10`: 1 info - endpoint added [Operation history](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/changes/workspaces/:workspaceId/usage/get.md) --- [API](https://skmtc.dev/florafauna-ai/apis/flora-ai-api.md) - [All operations](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/revisions/87cfe2c4ac29?raw)