feat(usage): add enterprise organization usage monitoring

Enterprise org admins had no way to see where their pooled credits go. The
billing page hides the usage-limit field and the credit-usage drill-down for
enterprise, and the credit-usage view is personal-scope only — so the one
audience that negotiates a pooled commitment was the one audience that could
not watch it burn.

Everything needed already existed in `usage_log`, which is the single source of
cost truth and is stamped `billing_entity_type='organization'` at charge time.
This adds the read surface over it, plus one narrow write so BYOK usage is
captured rather than discarded.

Settings → Organization → Usage tracking, gated on hosted + enterprise with a
`USAGE_MONITORING_ENABLED` self-hosted override, matching the other enterprise
features.

Five tabs, each answering one question: Overview (how much, and what kind of
work), Members, Workspaces (drill into one for its Sources and Workflows),
Models, BYOK. Only the visible tab's dimension is fetched — half the dimensions
heap-scan the ledger, so a tab nobody opens never pays for one. Every ranked
list closes with an explicit `Other (N more)` row so it reconciles to the
headline figure.

Track unbilled (BYOK) model usage
---------------------------------
BYOK spans already reached `costSummary` with real token counts and were
discarded at a single `if (modelData.total > 0)` gate. A new `model_unbilled`
usage_log category records them at zero cost, written only at the terminal
execution boundary and only when billing attribution is already resolved, so a
BYOK-only run with no billable target still bails safely instead of hitting the
attribution requirement. Every billing read over `usage_log` is `SUM(cost)`, so
zero-cost rows change no total anywhere.

Collapse organization settings onto the workspace plane
------------------------------------------------------
`/organization/[id]/settings/*` was a second plane with no UI entry point
anywhere, whose nine sections all already render on the workspace plane. It is
deleted, along with its renderer and unavailable page. `planes.organization` is
replaced by a single `unified.organizationSection` marker that now derives both
`ORGANIZATION_PLANE_UNIFIED_SECTIONS` and the section map in the workspace gate,
removing a hand-maintained duplicate. Usage-threshold emails now link to the
workspace-scoped billing page, and the two org-provisioning paths that could
strand an admin with zero workspaces now backfill one.

Shared chart module
-------------------
`LineChart` moves to `components/charts/` with a matching `BarChart` sibling
built from the same geometry, tooltip, and theme modules. The move also breaks
the import edge from the chart to `logs/utils` → `@/blocks/registry`, which
would otherwise have pulled the entire block registry into the settings chunk.
Logs dashboard renders identically.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

apps/docs/content/docs/en/platform/enterprise/index.mdx

@@ -53,6 +53,12 @@ Track configuration and security-relevant actions across your organization for c
 
 ---
 
+## Usage Tracking
+
+See where your organization's credits go — by member, workspace, model, and platform feature. See the [usage tracking guide](/platform/enterprise/usage-tracking).
+
+---
+
 ## Data Retention
 
 Configure how long execution logs, soft-deleted resources, and Chat data are kept before permanent deletion. See the [data retention guide](/platform/enterprise/data-retention).

apps/docs/content/docs/en/platform/enterprise/meta.json

@@ -10,6 +10,7 @@
     "custom-blocks",
     "whitelabeling",
     "audit-logs",
+    "usage-tracking",
     "data-retention",
     "data-drains",
     "forks"

apps/docs/content/docs/en/platform/enterprise/usage-tracking.mdx

@@ -0,0 +1,161 @@
+---
+title: Usage Tracking
+description: See where your organization's credits go, by member, workspace, and model
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { FAQ } from '@/components/ui/faq'
+import { Image } from '@/components/ui/image'
+
+Usage tracking shows how your organization consumes credits across every part of the platform — which members, which workspaces, which models, and which product features. Use it to monitor spend against your commitment, find what is driving it, and export the underlying events for chargeback.
+
+All figures are in **credits** (1 credit = $0.005). See [cost calculation](/platform/costs) for how credits are derived.
+
+---
+
+## Viewing usage
+
+Go to **Settings → Organization → Usage tracking** in your workspace.
+
+<Image src="/static/enterprise/usage-tracking-overview.png" alt="Usage tracking Overview tab showing the period selector, credits used against the organization limit, a daily usage chart, and a Sources breakdown listing Sim Chat, Workflow, and Agent block" width={900} height={578} />
+
+The period selector applies to every tab:
+
+| Period | What it covers |
+|--------|----------------|
+| **Current period** | Your organization's current billing period |
+| **Previous period** | The period immediately before it |
+| **Last 7 days** / **Last 30 days** | A rolling window ending now |
+| **Custom range** | Any range up to 92 days |
+
+<Callout type="info">
+  Daily bars are drawn in your browser's timezone, while a billing period begins at a fixed UTC instant. The first and last bar of a period can therefore be partial, and two admins in different timezones will see the same total split across slightly different days.
+</Callout>
+
+### Tabs
+
+| Tab | Answers |
+|-----|---------|
+| **Overview** | How much have we used, against what limit, and what kind of work was it |
+| **Members** | Which people are driving usage |
+| **Workspaces** | Which workspaces are driving usage — select one to drill in |
+| **Models** | Which models we are paying for |
+| **BYOK** | What ran on our own provider keys |
+
+Selecting a workspace opens its detail view, which splits that workspace's usage into **Sources** (what kind of work) and **Workflows** (the individual workflow runs). **Open logs** jumps to that workspace's execution logs.
+
+<Image src="/static/enterprise/usage-tracking-workspace-detail.png" alt="A workspace's detail view with a Sources section listing Sim Chat and Workflow, and a Workflows section ranking individual workflows by credits" width={900} height={598} />
+
+The two sections answer different questions, and the difference is the point: **Sources** adds up to the workspace's total, while **Workflows** covers only the workflow-run part of it. In the example above, Sources totals 4,435 credits but the workflows list only accounts for the 161 credits under Workflow — the other 4,274 came from Chat, which no workflow produced.
+
+---
+
+## What each source means
+
+A **source** is the part of the platform that consumed the credits. Every charge belongs to exactly one source, so the Sources breakdown always adds up to your total.
+
+| Source | Platform features that bill to it |
+|--------|-----------------------------------|
+| **Workflow** | Every workflow run — model calls made on Sim's hosted keys, hosted-key tool calls (web search, scraping, and similar), and the per-run base charge |
+| **Sim Chat** | The Chat panel, agent calls made through the API, and the email Inbox |
+| **Agent block** | The Agent block running inside a workflow |
+| **Knowledge Base** | Embedding documents on upload or connector sync, and semantic search queries |
+| **Wand** | Inline AI generation in editors |
+| **Enrichment** | Table column enrichment |
+| **Voice input** | Voice sessions |
+| **Voice output** | Spoken responses in deployed chats |
+| **Sim Chat (MCP)** | Retired. Appears only for historical periods |
+
+### Nuances worth knowing
+
+These follow from how charges are recorded, and they explain most questions about why a number looks the way it does.
+
+**Workflow covers the whole run, not just the base charge.** A workflow row includes three things: the models it called on Sim's hosted keys, any hosted-key tool calls, and the per-run base charge. Model usage typically dominates, but the per-run charge is not negligible — across a high-volume organization it commonly accounts for around a fifth of workflow spend, because it applies to every run whether or not the workflow calls a model.
+
+**Agent block is billed separately from the workflow that contains it.** An Agent block runs inside a workflow but is metered on its own, so its credits appear under **Agent block** rather than **Workflow**. Nothing is counted twice — but it also means Workflow alone understates what your workflows cost. Read the two lines together.
+
+**Sim Chat covers three surfaces.** The Chat panel, headless agent calls through the API, and the Inbox all record as **Sim Chat** and cannot be separated from one another. If you need per-surface attribution today, separate them by workspace instead.
+
+**Only workflow runs carry workflow attribution.** Chat, Agent block, Wand, Knowledge Base, and voice usage are not produced by a workflow and have no workflow attached. That is the gap between a workspace's **Sources** and **Workflows** sections shown above.
+
+**Some usage has no workspace.** Agent calls made through the API may not name a workspace, particularly from headless or self-hosted callers. That usage is grouped under **No workspace** on the Workspaces tab. It is still counted in your total.
+
+**Models excludes non-model charges.** The Models tab covers model usage only, so it will read lower than your period total — the difference is per-run base charges, hosted-key tool charges, and fixed charges such as voice sessions.
+
+<Callout type="warning">
+  Each tab is a different slice of the same charges, not an additional set of them. Members, Workspaces, and Sources each add up to your period total on their own; adding two tabs together double-counts.
+</Callout>
+
+---
+
+## Bring your own keys (BYOK)
+
+When a workspace or organization supplies its own provider key, Sim does not charge for that model usage. Those calls are still recorded so you can see the volume.
+
+The **BYOK** tab groups this usage by provider and reports **tokens** rather than credits, because the credit cost is zero by definition. Tokens on your own keys are not included in the credit totals anywhere else in the panel.
+
+<Callout type="info">
+  Tool calls and Chat usage made on your own keys are not yet recorded. BYOK currently covers model usage in workflow runs.
+</Callout>
+
+---
+
+## Exporting
+
+**Export** downloads the events behind the current period and filters as a CSV with columns `Date, Source, Description, Workflow, Credits`.
+
+**All events** opens the full ledger — every credit-consuming event, newest first, with its own filters and export.
+
+Very large exports are capped. When that happens the download still succeeds and Sim tells you it was truncated; narrow the date range to capture everything.
+
+---
+
+<FAQ items={[
+  {
+    question: "Who can view usage tracking?",
+    answer: "Organization owners and admins. On Sim Cloud you must be on the Enterprise plan. Regular members cannot see organization usage, including their own."
+  },
+  {
+    question: "Why doesn't the Models tab add up to my total?",
+    answer: "The Models tab covers model usage only. Your total also includes per-run base charges, hosted-key tool charges, and fixed charges such as voice sessions. Use the Sources breakdown on the Overview tab for a figure that reconciles to the total."
+  },
+  {
+    question: "Why is Sim Chat so much larger than Workflow?",
+    answer: "Sim Chat covers the Chat panel, API agent calls, and the Inbox together, and conversational usage is typically token-heavy. It is common for Chat to be the largest line in an organization that uses it."
+  },
+  {
+    question: "Can I see how much the Inbox or the API specifically costs?",
+    answer: "Not directly — both record as Sim Chat. Where those surfaces run in dedicated workspaces, the Workspaces tab gives you the equivalent breakdown."
+  },
+  {
+    question: "What is “No workspace”?",
+    answer: "Usage that was not attributed to a workspace, most often agent calls made through the API without a workspace context. It is included in your organization total."
+  },
+  {
+    question: "Is there an API for usage data?",
+    answer: "Not currently. Usage tracking is a settings surface; use the CSV export to move the data into your own systems."
+  },
+  {
+    question: "Why does a period show partial days at each end?",
+    answer: "Daily buckets follow your browser's timezone while billing periods begin at a fixed UTC instant, so the first and last bucket of a period can cover part of a day."
+  },
+  {
+    question: "Does this match my invoice?",
+    answer: "The Overview total for the current period is the same figure your billing page reports. Rolling windows such as Last 7 days do not align with a billing period and will not match an invoice."
+  }
+]} />
+
+---
+
+## Self-hosted setup
+
+Self-hosted deployments use environment variables instead of the billing/plan check.
+
+### Environment variables
+
+```bash
+USAGE_MONITORING_ENABLED=true
+NEXT_PUBLIC_USAGE_MONITORING_ENABLED=true
+```
+
+Once enabled, usage tracking is viewable in **Settings → Organization → Usage tracking** for organization owners and admins.

apps/docs/public/static/enterprise/usage-tracking-overview.png

@@ -160,7 +160,7 @@ const emailTemplates = {
       scope: 'organization',
       currentUsage: 500,
       limit: 500,
-      ctaLink: 'https://sim.ai/organization/org_123/settings/billing',
+      ctaLink: 'https://sim.ai/workspace/ws_123/settings/billing',
     }),
 
   // Operational notification emails

apps/docs/public/static/enterprise/usage-tracking-workspace-detail.png

@@ -0,0 +1,38 @@
+import { getOrganizationUsageBreakdownContract } from '@/lib/api/contracts/organization-usage'
+import {
+  defineInternalJsonRoute,
+  internalOrchestrationErrorPolicy,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import { getOrganizationUsageBreakdown } from '@/lib/billing/application/organization-usage/get-organization-usage-breakdown'
+import { organizationUsageOperations } from '@/lib/billing/application/organization-usage/operations'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * One route for all five dimensions: they share a scope, a window, a row shape, and
+ * authorization, so five routes would be five copies of the same mapping. Separate
+ * from the summary because three of the five heap-scan the ledger.
+ */
+export const GET = defineInternalJsonRoute({
+  contract: getOrganizationUsageBreakdownContract,
+  auth: internalSessionAuth,
+  operation: organizationUsageOperations.readBreakdown,
+  rateLimit: internalRateLimits.none({
+    reason:
+      'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
+  }),
+  errorPolicy: internalOrchestrationErrorPolicy,
+  mapInput: ({ params, query }) => ({
+    organizationId: params.id,
+    dimension: query.dimension,
+    workspaceId: query.workspaceId,
+    preset: query.preset,
+    startDate: query.startDate ? new Date(query.startDate) : undefined,
+    endDate: query.endDate ? new Date(query.endDate) : undefined,
+    limit: query.limit,
+  }),
+  useCase: getOrganizationUsageBreakdown,
+  present: (result) => result,
+})

apps/sim/app/api/emails/preview/route.ts

@@ -0,0 +1,39 @@
+import { listOrganizationUsageEventsContract } from '@/lib/api/contracts/organization-usage'
+import {
+  defineInternalJsonRoute,
+  internalOrchestrationErrorPolicy,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import { listOrganizationUsageEvents } from '@/lib/billing/application/organization-usage/list-organization-usage-events'
+import { organizationUsageOperations } from '@/lib/billing/application/organization-usage/operations'
+import type { InternalUsageLogSource } from '@/lib/billing/usage-sources'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * The raw ledger, paged. Separate from the summary because it owns a cursor
+ * lifecycle and its own staleness — folding it in would re-run the headline
+ * aggregate on every scroll.
+ */
+export const GET = defineInternalJsonRoute({
+  contract: listOrganizationUsageEventsContract,
+  auth: internalSessionAuth,
+  operation: organizationUsageOperations.listEvents,
+  rateLimit: internalRateLimits.none({
+    reason:
+      'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
+  }),
+  errorPolicy: internalOrchestrationErrorPolicy,
+  mapInput: ({ params, query }) => ({
+    organizationId: params.id,
+    preset: query.preset,
+    startDate: query.startDate ? new Date(query.startDate) : undefined,
+    endDate: query.endDate ? new Date(query.endDate) : undefined,
+    source: query.source as InternalUsageLogSource[] | undefined,
+    limit: query.limit,
+    cursor: query.cursor,
+  }),
+  useCase: listOrganizationUsageEvents,
+  present: (result) => result,
+})

apps/sim/app/api/organizations/[id]/usage/breakdown/route.ts

@@ -0,0 +1,81 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { exportOrganizationUsageContract } from '@/lib/api/contracts/organization-usage'
+import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import {
+  exportOrganizationUsageEvents,
+  type OrganizationUsageExportRow,
+} from '@/lib/billing/application/organization-usage/export-organization-usage-events'
+import { formatCreditsLabel } from '@/lib/billing/credits/conversion'
+import type { InternalUsageLogSource } from '@/lib/billing/usage-sources'
+import { ForbiddenOperationError } from '@/lib/core/application'
+import { formatCsvValue, toCsvRow } from '@/lib/core/utils/csv'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+
+const logger = createLogger('OrganizationUsageExportAPI')
+
+const CSV_HEADER = toCsvRow(['Date', 'Source', 'Description', 'Workflow', 'Credits'])
+
+/** `formatCsvValue` neutralizes formula injection — model and workflow names are user-controlled. */
+function toCsvLine(row: OrganizationUsageExportRow): string {
+  return toCsvRow([
+    formatCsvValue(row.createdAt),
+    formatCsvValue(row.source),
+    formatCsvValue(row.description),
+    formatCsvValue(row.workflowName ?? ''),
+    formatCsvValue(formatCreditsLabel(row.credits)),
+  ])
+}
+
+/**
+ * A raw handler rather than a JSON builder: the body is `text/csv`, and the response
+ * carries `X-Export-Truncated` so the client can tell the user their range was capped
+ * rather than silently handing them a partial file.
+ */
+export const GET = withRouteHandler(async (request: NextRequest, context) => {
+  try {
+    const session = await getSession()
+    const sessionId = session?.session?.id
+    if (!session?.user?.id || !sessionId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const parsed = await parseRequest(exportOrganizationUsageContract, request, context, {
+      validationErrorResponse: (error) =>
+        NextResponse.json(
+          { error: getValidationErrorMessage(error, 'Invalid query parameters') },
+          { status: 400 }
+        ),
+    })
+    if (!parsed.success) return parsed.response
+
+    const { query, params } = parsed.data
+    const result = await exportOrganizationUsageEvents.execute({
+      principal: { kind: 'session', userId: session.user.id, sessionId },
+      input: {
+        organizationId: params.id,
+        preset: query.preset,
+        startDate: query.startDate ? new Date(query.startDate) : undefined,
+        endDate: query.endDate ? new Date(query.endDate) : undefined,
+        source: query.source as InternalUsageLogSource[] | undefined,
+      },
+    })
+
+    const csv = [CSV_HEADER, ...result.rows.map(toCsvLine)].join('\n')
+    return new NextResponse(csv, {
+      headers: {
+        'Content-Type': 'text/csv; charset=utf-8',
+        'Content-Disposition': `attachment; filename="organization-usage-${params.id}.csv"`,
+        ...(result.truncated ? { 'X-Export-Truncated': '1' } : {}),
+      },
+    })
+  } catch (error) {
+    if (error instanceof ForbiddenOperationError) {
+      return NextResponse.json({ error: error.message }, { status: 403 })
+    }
+    logger.error('Failed to export organization usage', { error: getErrorMessage(error) })
+    return NextResponse.json({ error: 'Failed to export usage' }, { status: 500 })
+  }
+})

apps/sim/app/api/organizations/[id]/usage/events/route.ts

@@ -0,0 +1,36 @@
+import { getOrganizationUsageSummaryContract } from '@/lib/api/contracts/organization-usage'
+import {
+  defineInternalJsonRoute,
+  internalOrchestrationErrorPolicy,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import { getOrganizationUsageSummary } from '@/lib/billing/application/organization-usage/get-organization-usage-summary'
+import { organizationUsageOperations } from '@/lib/billing/application/organization-usage/operations'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Everything above the fold in one round trip. Kept separate from the breakdown
+ * route because every read here is index-covered, and folding in a dimension that
+ * heap-scans would put that cost on first paint.
+ */
+export const GET = defineInternalJsonRoute({
+  contract: getOrganizationUsageSummaryContract,
+  auth: internalSessionAuth,
+  operation: organizationUsageOperations.readSummary,
+  rateLimit: internalRateLimits.none({
+    reason:
+      'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
+  }),
+  errorPolicy: internalOrchestrationErrorPolicy,
+  mapInput: ({ params, query }) => ({
+    organizationId: params.id,
+    preset: query.preset,
+    startDate: query.startDate ? new Date(query.startDate) : undefined,
+    endDate: query.endDate ? new Date(query.endDate) : undefined,
+    timezone: query.timezone,
+  }),
+  useCase: getOrganizationUsageSummary,
+  present: (result) => result,
+})