fix(usage): correct reconciliation, gating, and error classification

Second review round. The findings that were real, and what changed.

Billing aggregates. `getBillingPeriodWorkflowRunCount` counts distinct workflow
executions with no category predicate, and its own contract says executions with
no billable usage are excluded. A BYOK-only run with a zero base charge writes
nothing but a `model_unbilled` row, so it would newly appear in a figure that
feeds the enterprise billing preview; the count now excludes unbilled categories.
`recordUsage` also admits an unbilled entry only at exactly zero cost — the whole
safety argument for the category is that every aggregate is `SUM(cost)`.

Reconciliation. Breakdown rows and their remainder were each rounded to credits
independently and compared against a separately rounded total, so with sub-credit
fractions they could not add up — which is precisely what the `Other` row exists
to prevent. They now go through one `apportionCredits` pass. The event list and
the CSV also counted a row stamped exactly on the window end, which the summary
excluded, because the ledger filter is `lte` while an analytics window is
half-open; `endDateExclusive` makes the two agree.

BYOK ranking. The tab is denominated in tokens and every row costs zero, so
ranking by cost fell through to an alphabetical tiebreak — the "top providers"
were whichever sorted first, and the hidden tail's tokens were dropped entirely.
It ranks by tokens, and the remainder carries its own token total.

Gating. The usage entry carried `hideWhenBillingDisabled` copied from Members,
but the sidebar applies that filter before it consults `selfHostedOverride`, so
it hid the section from exactly the deployment the override exists to serve.
Members can carry the flag because it has no override to reach.

Error classification. An over-long custom range threw past the orchestration
policy and answered 500 on all four routes. A shared policy maps it to 400, the
export route makes the same classification in its catch, and the picker now
refuses the range up front rather than committing one the API will reject.

Also: the segmented meter's overage tone was unreachable (both counts clamped to
`segments`, so the comparison could never hold) and now scales both against
`max(total, used)`; the allowance is only compared against the current period,
since a rolling window can exceed a limit neither period did; `source` accepts a
scalar and validates against the source enum instead of an unchecked cast; the
bar chart's axis tick uses the same unit-aware formatter as its tooltip; and
`assertValidTimezone` strips control characters before echoing a rejected value.

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

Author: icecrasher321

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

@@ -1,12 +1,12 @@
 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'
+import { organizationUsageErrorPolicy } from '@/app/api/organizations/[id]/usage/error-policy'
 
 export const dynamic = 'force-dynamic'
 
@@ -23,7 +23,7 @@ export const GET = defineInternalJsonRoute({
     reason:
       'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
   }),
-  errorPolicy: internalOrchestrationErrorPolicy,
+  errorPolicy: organizationUsageErrorPolicy,
   mapInput: ({ params, query }) => ({
     organizationId: params.id,
     dimension: query.dimension,

apps/sim/app/api/organizations/[id]/usage/error-policy.ts

@@ -0,0 +1,23 @@
+import {
+  extendInternalErrorPolicy,
+  internalErrorResponse,
+  internalOrchestrationErrorPolicy,
+} from '@/lib/api/server/routes'
+import { UsageWindowRangeTooLargeError } from '@/lib/billing/core/usage-analytics'
+
+/**
+ * The window resolver throws when a custom range exceeds its cap, which is a
+ * caller-fixable input error rather than a fault. Without this it fell through to
+ * the orchestration policy's `unhandled` branch and every over-long range answered
+ * `500 Internal server error`, so the client could neither surface the real reason
+ * nor tell the two apart.
+ *
+ * Shared by all four usage routes so they cannot classify the same throw differently.
+ */
+export const organizationUsageErrorPolicy = extendInternalErrorPolicy(
+  internalOrchestrationErrorPolicy,
+  (error) =>
+    error instanceof UsageWindowRangeTooLargeError
+      ? internalErrorResponse(400, { error: error.message })
+      : null
+)

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

@@ -1,13 +1,12 @@
 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'
+import { organizationUsageErrorPolicy } from '@/app/api/organizations/[id]/usage/error-policy'
 
 export const dynamic = 'force-dynamic'
 
@@ -24,13 +23,13 @@ export const GET = defineInternalJsonRoute({
     reason:
       'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
   }),
-  errorPolicy: internalOrchestrationErrorPolicy,
+  errorPolicy: organizationUsageErrorPolicy,
   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,
+    source: query.source,
     limit: query.limit,
     cursor: query.cursor,
   }),

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

@@ -8,8 +8,8 @@ import {
   exportOrganizationUsageEvents,
   type OrganizationUsageExportRow,
 } from '@/lib/billing/application/organization-usage/export-organization-usage-events'
+import { UsageWindowRangeTooLargeError } from '@/lib/billing/core/usage-analytics'
 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'
@@ -59,7 +59,7 @@ export const GET = withRouteHandler(async (request: NextRequest, context) => {
         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,
+        source: query.source,
       },
     })
 
@@ -75,6 +75,11 @@ export const GET = withRouteHandler(async (request: NextRequest, context) => {
     if (error instanceof ForbiddenOperationError) {
       return NextResponse.json({ error: error.message }, { status: 403 })
     }
+    // A range over the cap is the caller's input, not a fault — the same
+    // classification the three JSON routes make through `organizationUsageErrorPolicy`.
+    if (error instanceof UsageWindowRangeTooLargeError) {
+      return NextResponse.json({ error: error.message }, { status: 400 })
+    }
     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/summary/route.ts

@@ -1,12 +1,12 @@
 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'
+import { organizationUsageErrorPolicy } from '@/app/api/organizations/[id]/usage/error-policy'
 
 export const dynamic = 'force-dynamic'
 
@@ -23,7 +23,7 @@ export const GET = defineInternalJsonRoute({
     reason:
       'Authenticated org-admin settings read, gated on enterprise entitlement and billing authority',
   }),
-  errorPolicy: internalOrchestrationErrorPolicy,
+  errorPolicy: organizationUsageErrorPolicy,
   mapInput: ({ params, query }) => ({
     organizationId: params.id,
     preset: query.preset,

apps/sim/app/workspace/[workspaceId]/settings/[section]/page.test.tsx

@@ -52,6 +52,7 @@ vi.mock('@/components/settings/navigation', () => ({
     sessions: 'sessions',
     'data-retention': 'data-retention',
     'data-drains': 'data-drains',
+    usage: 'usage',
     whitelabeling: 'whitelabeling',
   },
   workspaceSectionUsesPermissionConfig: vi.fn((section: string) =>

apps/sim/app/workspace/[workspaceId]/settings/components/segmented-meter/segmented-meter.tsx

@@ -21,9 +21,16 @@ interface SegmentedMeterProps {
  * affordance answering the same question, and previously only one existed.
  */
 export function SegmentedMeter({ used, total, segments, className }: SegmentedMeterProps) {
-  const filledSegments =
-    total > 0 ? Math.min(segments, Math.round((used / total) * segments)) : used > 0 ? segments : 0
-  const allowedSegments = total > 0 ? segments : 0
+  /**
+   * Both counts are measured against the larger of the two, so an overage has
+   * somewhere to render. Scaling the fill by `total` and clamping it meant
+   * `filledSegments` and the allowance were both `segments` whenever usage exceeded
+   * the limit, and the overage tone below could never be reached — the meter simply
+   * showed full.
+   */
+  const scale = Math.max(total, used)
+  const filledSegments = scale > 0 ? Math.min(segments, Math.round((used / scale) * segments)) : 0
+  const allowedSegments = scale > 0 ? Math.round((total / scale) * segments) : 0
 
   return (
     <div className={cn('flex items-center gap-1', className)} aria-hidden='true'>

apps/sim/components/charts/bar-chart.tsx

@@ -286,7 +286,9 @@ function BarChartComponent({
             fontSize={CHART_TICK_FONT_SIZE}
             fill={CHART_TICK_FILL}
           >
-            {formatChartCompactNumber(maxValue)}
+            {/* Same formatter the tooltip uses, or the axis and the hover disagree
+                about what the numbers mean on any non-`credits` unit. */}
+            {formatValue(maxValue)}
           </text>
           <text
             x={padding.left - 8}

apps/sim/components/settings/navigation.ts

@@ -504,7 +504,16 @@ export const SETTINGS_SECTION_REGISTRY: readonly SettingsSectionRegistryEntry[]
       description: 'Monitor credit usage across your organization.',
       group: 'organization',
       order: 1,
-      hideWhenBillingDisabled: true,
+      /**
+       * Deliberately no `hideWhenBillingDisabled`, unlike Members above.
+       *
+       * The sidebar applies that filter *before* it consults `selfHostedOverride`,
+       * so pairing the two hid this section from exactly the deployment the
+       * override exists to serve: self-hosted, billing off, `USAGE_MONITORING_ENABLED`
+       * on. Members can carry the flag because it has no override to reach. Here the
+       * two gates below already answer both cases — hosted needs the plan, and
+       * self-hosted needs the flag.
+       */
       requiresHosted: true,
       requiresEnterprise: true,
       selfHostedOverride: SETTINGS_SELF_HOSTED_OVERRIDES.usageMonitoring,

apps/sim/ee/organization-usage/components/usage-consumers.tsx

@@ -181,7 +181,9 @@ export function UsageConsumers({
             {`Other (${breakdown.other.rowCount} more)`}
           </span>
           <span className='w-[72px] flex-shrink-0 text-right text-[var(--text-muted)] text-caption tabular-nums'>
-            {showTokensOnly ? '—' : breakdown.other.credits.toLocaleString()}
+            {showTokensOnly
+              ? formatChartCompactNumber(breakdown.other.tokens)
+              : breakdown.other.credits.toLocaleString()}
           </span>
           {trailingSlot && (
             <span className={cn(trailingSlot, 'flex-shrink-0')} aria-hidden='true' />