> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/reference/workspaces/getworkspaceusage.md).

# Get workspace balance and usage

Get workspace balance and usage with the FLORA API: GET /workspaces/{workspaceId}/usage.

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.

```http
GET https://app.flora.ai/api/v1/workspaces/{workspaceId}/usage
```

* **Auth:** API key as a bearer token, `Authorization: Bearer $FLORA_API_KEY`. See [Authentication](https://docs.flora.ai/api/platform/authentication.md).
* **TypeScript SDK:** `client.workspaces.getUsage()`.
* **Operation ID:** `getWorkspaceUsage`.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET 'https://app.flora.ai/api/v1/workspaces/ws_abc123/usage' \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { FloraClient } from '@flora-ai/flora';

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

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

{% endtab %}
{% endtabs %}

## Path parameters

| Name          | Type   | Required | Description                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| `workspaceId` | string | Yes      | Workspace identifier. Pattern: `^ws_\S+$`. Example: `ws_abc123`. |

## Query parameters

| Name         | Type   | Required | Description                                                                                                                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_date` | string | No       | First UTC day to include (YYYY-MM-DD), at most 30 days before end\_date. Defaults to 29 days before end\_date. Pattern: `^\d{4}-\d{2}-\d{2}$`. Example: `2026-08-01`. |
| `end_date`   | string | No       | Last UTC day to include (YYYY-MM-DD), no later than today. Defaults to today (UTC). Pattern: `^\d{4}-\d{2}-\d{2}$`. Example: `2026-08-01`.                            |

## Responses

### 200: Workspace usage returned.

| Field                     | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`            | string | Yes      | Workspace identifier. Pattern: `^ws_\S+$`. Example: `ws_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `currency`                | string | Yes      | Currency of every cost in this response. Always `USD`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `balance_scope`           | string | Yes      | 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. One of: `caller`, `workspace`.                                                                                                                                                                                                                                                                                          |
| `available_cost`          | number | Yes      | 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. At least 0. |
| `member_limit`            | object | No       | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `member_limit.limit_cost` | number | Yes      | The limit in USD. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `member_limit.period`     | string | Yes      | month: the limit resets each monthly usage cycle. all\_time: it never resets. One of: `month`, `all_time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `spend`                   | object | Yes      | 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. See the `spend` shapes below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

<details>

<summary>spend shapes</summary>

Field paths in this block are relative to `spend`.

`spend` takes one of 2 shapes, set by `status`.

**Shape 1: `status` is `available`.**

| Field                        | Type    | Required | Description                                                                                                                                                   |
| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                     | string  | Yes      | Always `available`.                                                                                                                                           |
| `scope`                      | string  | Yes      | The totals cover every run charged in the workspace, by any member or agent. Always `workspace`.                                                              |
| `period`                     | object  | Yes      | Inclusive UTC day range the totals cover                                                                                                                      |
| `period.start_date`          | string  | Yes      | UTC calendar day in YYYY-MM-DD form. Pattern: `^\d{4}-\d{2}-\d{2}$`. Example: `2026-08-01`.                                                                   |
| `period.end_date`            | string  | Yes      | UTC calendar day in YYYY-MM-DD form. Pattern: `^\d{4}-\d{2}-\d{2}$`. Example: `2026-08-01`.                                                                   |
| `total_cost`                 | number  | Yes      | USD charged in the workspace in the period; the same figure as the in-app Usage tab for the same range. At least 0.                                           |
| `classified_runs`            | integer | Yes      | Sum of the classified run categories in runs\_by\_category. Spend on runs whose output modality cannot be classified appears only in total\_cost. At least 0. |
| `runs_by_category`           | object  | Yes      | Charged runs in the period, by classified output modality. Runs whose modality cannot be classified are not counted.                                          |
| `runs_by_category.text`      | integer | Yes      | Text generation runs. At least 0.                                                                                                                             |
| `runs_by_category.image`     | integer | Yes      | Image generation runs. At least 0.                                                                                                                            |
| `runs_by_category.video`     | integer | Yes      | Video generation runs. At least 0.                                                                                                                            |
| `runs_by_category.audio`     | integer | Yes      | Audio generation runs. At least 0.                                                                                                                            |
| `runs_by_category.technique` | integer | Yes      | Technique runs. At least 0.                                                                                                                                   |

**Shape 2: `status` is `unavailable`.**

| Field    | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                              |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status` | string | Yes      | Always `unavailable`.                                                                                                                                                                                                                                                                                                                                                    |
| `reason` | string | Yes      | 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. One of: `entitlement_missing`, `permission_missing`, `summary_unavailable`. |

</details>

## Errors

Every error has the same body: `error.code`, `error.message`, and `error.fields` on validation errors. See [Errors](https://docs.flora.ai/api/platform/errors.md) for how to recover from each code.

| Status | Code                                         | Meaning                                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `input_validation_error`     | The body isn't valid JSON, or an input failed validation (`fields` lists each one). |
| 401    | `unauthorized`, `invalid_api_key`            | The API key is missing, invalid or revoked.                                         |
| 402    | `insufficient_credits`                       | The workspace balance is too low for this request.                                  |
| 403    | `forbidden`, `paid_plan_required`            | The key can't do this, or the workspace plan doesn't include it.                    |
| 404    | `not_found`                                  | The resource doesn't exist or isn't visible to this key.                            |
| 409    | `idempotency_duplicate`, `revision_conflict` | Duplicate `Idempotency-Key` or a stale `base_revision`.                             |
| 429    | `rate_limited`                               | Too many requests. Back off and retry.                                              |
| 500    | `unknown_error`, `internal_error`            | Something failed on FLORA's side. Retry with backoff.                               |
| 503    | `temporarily_unavailable`                    | Authorization is temporarily unavailable. Retry later.                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/reference/workspaces/getworkspaceusage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
