> 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/guides/organizations.md).

# Organization usage

Read usage charged across an organization's FLORA workspaces in US dollars, broken down by workspace, member, model or day, or export it as CSV.

An organization owns billing for one or more workspaces. If yours runs a workspace per client or per project, these endpoints read what was charged across all of them, so spend can flow into your own reporting or margin tools without opening the FLORA dashboard.

## Who can call these endpoints

* The organization must have multiple workspaces enabled (an Enterprise feature).
* The user behind the credential must hold billing permissions in the organization.
* An API key works for the organization that owns a workspace where the key has **billing** permission. An OAuth token works for any organization the user administers.

Requests that fail these checks return `403 forbidden`. Find an organization's ID (`org_...`) as `organization_id` on each item from `GET /workspaces`.

## Get usage totals and a breakdown

```bash
curl "https://app.flora.ai/api/v1/organizations/org_abc123/usage?start_date=2026-08-01&end_date=2026-08-31&group_by=workspace" \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

Response:

```json
{
  "organization_id": "org_abc123",
  "period": { "start_date": "2026-08-01", "end_date": "2026-08-31" },
  "total_cost": 1145.21,
  "total_runs": 2310,
  "runs_by_category": {
    "text": 40,
    "image": 1800,
    "video": 420,
    "audio": 0,
    "technique": 50,
    "unknown": 0
  },
  "workspaces": [{ "workspace_id": "ws_a", "name": "Client A" }],
  "group_by": "workspace",
  "by_workspace": [{ "workspace_id": "ws_a", "name": "Client A", "cost": 640.1, "runs": 1200 }]
}
```

* `start_date` and `end_date` are inclusive UTC calendar days. Omit both for the last 30 days. Ranges are capped at 366 days.
* All cost values are US dollars. `total_cost` matches the **Organization Analytics** tab (a per-day aggregate converted once). Breakdown rows and CSV exports sum exact per-charge amounts, so they can differ from it by rounding, well under 0.1%. Reconcile per-row data against the breakdown or the export, not against `total_cost`.
* `runs_by_category.unknown` includes Technique runs recorded before Techniques became their own category; the Organization Analytics tab counts them the same way.
* `group_by` adds one breakdown per request: `workspace`, `user` (members summed across every workspace, plus agent-attributed spend), `model` (Technique runs appear as a single `technique` row), or `day`.
* `by_user` lists people who currently belong to one of the workspaces. Spend by removed members stays in the totals but isn't itemized; the CSV export carries every generation's user email.
* Model rows are keyed by the endpoint that was billed. A generation requested through Auto routing appears under the endpoint Auto chose, while the CSV export's Model column shows the model as requested.
* A `model` breakdown on an organization with more than 50 workspaces reads the top 50 by cost and says so in `coverage`; the totals still cover every workspace.
* Spend on a model retired during the period isn't dropped: it's reported as `unattributed_cost` alongside `by_model`.

## Export per-generation rows as CSV

For per-project and per-user detail, queue an export (same 366-day cap) and poll it:

```bash
curl -X POST "https://app.flora.ai/api/v1/organizations/org_abc123/usage-exports" \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2026-08-01","end_date":"2026-08-31"}'
```

The response is the export with `status: "queued"`. Poll until it completes:

```bash
curl "https://app.flora.ai/api/v1/organizations/org_abc123/usage-exports/export_abc123" \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

```json
{
  "export_id": "export_abc123",
  "status": "completed",
  "row_count": 2310,
  "files": [
    {
      "part": 1,
      "filename": "organization-analytics-export-2026-08-01-to-2026-08-31.csv",
      "download_url": "https://...",
      "row_count": 2310,
      "byte_size": 412331
    }
  ]
}
```

Columns: Workspace, Date, Project ID, Project Name, User Email, Modality, Model, Media URL, Cost, Modifiers, Usage pool. Large exports are split into numbered parts.

## Common endpoints

| Method | Path                                                       | Description                                                                                                                 |
| ------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/organizations/{organizationId}/usage`                    | [Usage totals with an optional breakdown](https://docs.flora.ai/api/reference/organizations/getorganizationusage.md)        |
| POST   | `/organizations/{organizationId}/usage-exports`            | [Queue a per-generation CSV export](https://docs.flora.ai/api/reference/organizations/createorganizationusageexport.md)     |
| GET    | `/organizations/{organizationId}/usage-exports/{exportId}` | [Poll an export and get its download URLs](https://docs.flora.ai/api/reference/organizations/getorganizationusageexport.md) |

## Notes

* Only the user who requested an export can read it. Exports are kept for seven days.
* Each `download_url` works for anyone who holds it until the export expires. Treat it like a secret: keep it out of logs and tickets, and fetch it server-side.
* One export per user can be in progress at a time; a second request within a few minutes returns `429 rate_limited`.
* The credential's user also receives the download link by email, as when exporting from the dashboard.
* For one workspace's balance and recent spend, use `GET /workspaces/{workspaceId}/usage`; see [Workspaces](https://docs.flora.ai/api/guides/workspaces.md#check-balance-and-spend).


---

# 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/guides/organizations.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.
