Organization usage

An organization owns billing for one or more workspaces. Enterprise organizations that run a workspace per client or per project can read the usage charged across all of them, so spend can flow into an internal reporting or margin tool 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 is tied to one workspace, so it can report on the organization that owns that workspace. An OAuth token can report on any organization the user administers.

Requests that fail these checks return 403 forbidden. Find an organization’s ID as organization_id on each item returned by GET /api/v1/workspaces.

Get usage totals and a breakdown

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

Response:

{
  "organization_id": "org_XXXX",
  "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.
• cost values are USD. total_cost is the figure the Organization Analytics tab shows (a per-day aggregate converted once); breakdown rows and CSV exports sum exact per-charge amounts and 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 technique became its own category; the Organization Analytics tab counts them the same way.
• Model rows are keyed by the endpoint that was billed. A generation requested through Auto routing appears under the endpoint Auto selected, whereas the CSV export’s Model column shows the model as requested.
• 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 hold a membership in one of the workspaces. Spend by members who have since been removed stays in the totals but is not itemized; the CSV export carries every generation’s user email.
• 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.
• Model rows cover the live and static model catalogs. Spend on an endpoint retired from both during the period is not dropped: it is 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 as the usage read) and poll it:

curl -X POST "https://app.flora.ai/api/v1/organizations/org_XXXX/usage-exports" \
  -H "Authorization: Bearer ak_XXXX" \
  -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:

curl "https://app.flora.ai/api/v1/organizations/org_XXXX/usage-exports/export_XXXX" \
  -H "Authorization: Bearer ak_XXXX"

{
  "export_id": "export_XXXX",
  "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	/api/v1/organizations/{organizationId}/usage	Usage totals with an optional breakdown
POST	/api/v1/organizations/{organizationId}/usage-exports	Queue a per-generation CSV export
GET	/api/v1/organizations/{organizationId}/usage-exports/{exportId}	Poll an export and get its download URLs

Notes

• Only the user who requested an export can read it. Exports are kept for seven days.
• Each download_url is a capability link: anyone holding it can fetch that file 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 may 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, exactly as when exporting from the dashboard.