improvement(usage): add a period-labelled chart to the workspace drill-down

The Workspaces drill-down showed two ranked lists and no chart, and stated
its window nowhere — the period picker lives on the list behind it, so the
carried-over window was invisible once you were inside.

- Draw the summary's headline, delta, and trend chart at the top of the
  drill-down, narrowed to that workspace
- Label its section with the selected period, which is now the only place
  the drill-down states its window
- Carry workspaceId through the summary contract, route, use case, query
  key, and hook so the chart reads one workspace
- Move the workspace narrowing onto buildUsageAnalyticsScope, so the chart,
  the headline, and both lists derive it from one definition instead of the
  breakdown query owning a second copy

The comparison window takes the same narrowing, or the delta would measure
one workspace against the whole organization. No allowance figure is shown,
unlike the Overview: the limit is pooled across the organization and would
read as that workspace's own cap.

Author: icecrasher321

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

@@ -26,6 +26,7 @@ export const GET = defineInternalJsonRoute({
   errorPolicy: organizationUsageErrorPolicy,
   mapInput: ({ params, query }) => ({
     organizationId: params.id,
+    workspaceId: query.workspaceId,
     preset: query.preset,
     startDate: query.startDate ? new Date(query.startDate) : undefined,
     endDate: query.endDate ? new Date(query.endDate) : undefined,

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

@@ -183,6 +183,18 @@ export function UsageMonitoring({
     limit: rowLimitFor('source'),
     ...(workspace ? { workspaceId: workspace } : {}),
   })
+  /**
+   * The same headline and trend the Overview draws, narrowed to this workspace.
+   *
+   * A second summary rather than a figure derived from the lists below it: they carry
+   * totals but no time series, and the shape of the period is the question the chart
+   * answers. It is also the only place the drill-down states its window, which is why
+   * its section is labelled with the period rather than with the word "Usage".
+   */
+  const workspaceSummary = useOrganizationUsageSummary(organizationId, window, {
+    enabled: isWorkspaceDetail,
+    ...(workspace ? { workspaceId: workspace } : {}),
+  })
   // Already cached by Members and Billing, so the meter costs nothing extra and
   // cannot report a different allowance than they do.
   const billing = useOrganizationBilling(organizationId)
@@ -321,6 +333,23 @@ export function UsageMonitoring({
             : []
         }
       >
+        {/*
+          Labelled with the period, not "Usage": the picker lives on the list behind
+          this view, so once you are in here the window is carried but invisible — and
+          a total with no stated period is a number people read as all-time. The
+          heading the chart already needs is where that belongs.
+
+          No allowance passed, unlike the Overview: the limit is pooled across the
+          whole organization, and printing it under one workspace's figure would read
+          as that workspace's own cap.
+        */}
+        <SettingsSection label={periodLabel}>
+          <UsageSummary
+            summary={workspaceSummary.data}
+            isLoading={workspaceSummary.isLoading}
+            isError={workspaceSummary.isError}
+          />
+        </SettingsSection>
         {/*
           Sources first, because in most workspaces the majority of usage is Chat
           rather than workflow runs — and a workflow list alone hid that behind a

apps/sim/hooks/queries/organization-usage.ts

@@ -26,19 +26,28 @@ export const ORGANIZATION_USAGE_EVENTS_STALE_TIME = 30 * 1000
 
 const EVENTS_PAGE_SIZE = 50
 
+interface UseSummaryOptions {
+  /** The panel fetches the drill-down's chart only while that view is open. */
+  enabled?: boolean
+  /** Narrows to one workspace, for the Workspaces drill-down. */
+  workspaceId?: string
+}
+
 export function useOrganizationUsageSummary(
   organizationId: string | undefined,
-  window: OrganizationUsageWindowKey
+  window: OrganizationUsageWindowKey,
+  options: UseSummaryOptions = {}
 ) {
+  const { workspaceId } = options
   return useQuery({
-    queryKey: organizationUsageKeys.summary(organizationId ?? '', window),
+    queryKey: organizationUsageKeys.summary(organizationId ?? '', window, workspaceId),
     queryFn: ({ signal }): Promise<OrganizationUsageSummary> =>
       requestJson(getOrganizationUsageSummaryContract, {
         params: { id: organizationId as string },
-        query: { ...window },
+        query: { ...window, ...(workspaceId ? { workspaceId } : {}) },
         signal,
       }),
-    enabled: Boolean(organizationId),
+    enabled: Boolean(organizationId) && (options.enabled ?? true),
     staleTime: ORGANIZATION_USAGE_SUMMARY_STALE_TIME,
     // Changing the period should dim the current figures rather than blank them.
     placeholderData: keepPreviousData,

apps/sim/hooks/queries/utils/organization-usage-keys.ts

@@ -23,8 +23,13 @@ export interface OrganizationUsageWindowKey {
 
 export const organizationUsageKeys = {
   all: (organizationId: string) => ['organizations', 'detail', organizationId, 'usage'] as const,
-  summary: (organizationId: string, window: OrganizationUsageWindowKey) =>
-    [...organizationUsageKeys.all(organizationId), 'summary', window] as const,
+  summary: (
+    organizationId: string,
+    window: OrganizationUsageWindowKey,
+    /** Set only inside the Workspaces drill-down, whose chart reads one workspace. */
+    workspaceId?: string
+  ) =>
+    [...organizationUsageKeys.all(organizationId), 'summary', window, workspaceId ?? ''] as const,
   breakdowns: (organizationId: string, window: OrganizationUsageWindowKey) =>
     [...organizationUsageKeys.all(organizationId), 'breakdown', window] as const,
   breakdown: (

apps/sim/lib/api/contracts/organization-usage.ts

@@ -126,13 +126,24 @@ const organizationUsageWindowQuerySchema = z.object({
     .default('UTC'),
 })
 
-export const organizationUsageSummaryQuerySchema = organizationUsageWindowQuerySchema
+/**
+ * Narrows a read to one workspace, for the Workspaces drill-down.
+ *
+ * Declared once and spread into both query schemas: the drill-down draws its chart
+ * from the summary and its lists from the breakdown, so a workspace filter either
+ * surface could express alone is one the two could disagree about.
+ */
+const usageWorkspaceScopeShape = {
+  workspaceId: workspaceIdSchema.optional(),
+} as const
+
+export const organizationUsageSummaryQuerySchema =
+  organizationUsageWindowQuerySchema.extend(usageWorkspaceScopeShape)
 export type OrganizationUsageSummaryQuery = z.input<typeof organizationUsageSummaryQuerySchema>
 
 export const organizationUsageBreakdownQuerySchema = organizationUsageWindowQuerySchema.extend({
+  ...usageWorkspaceScopeShape,
   dimension: usageBreakdownDimensionSchema,
-  /** Narrows the breakdown to one workspace, for the Workspaces drill-down. */
-  workspaceId: workspaceIdSchema.optional(),
   limit: usageLimitSchema(50, 10),
 })
 export type OrganizationUsageBreakdownQuery = z.input<typeof organizationUsageBreakdownQuerySchema>

apps/sim/lib/billing/application/organization-usage/get-organization-usage-breakdown.ts

@@ -78,8 +78,8 @@ export const getOrganizationUsageBreakdown = defineAuthorizedOrganizationUsageUs
       customEnd: input.endDate,
       timezone: input.timezone,
     })
-    const scope = buildUsageAnalyticsScope(context.billingEntity, window)
-    const raw = await readUsageBreakdown(scope, input.dimension, input.workspaceId)
+    const scope = buildUsageAnalyticsScope(context.billingEntity, window, input.workspaceId)
+    const raw = await readUsageBreakdown(scope, input.dimension)
 
     /**
      * Re-key onto what the panel actually displays before ranking.

apps/sim/lib/billing/application/organization-usage/get-organization-usage-summary.ts

@@ -20,6 +20,8 @@ export interface OrganizationUsageSummaryInput {
   startDate?: Date
   endDate?: Date
   timezone: string
+  /** Narrows to one workspace, for the Workspaces drill-down. */
+  workspaceId?: string
 }
 
 export interface OrganizationUsageSummaryResult {
@@ -47,7 +49,7 @@ export const getOrganizationUsageSummary = defineAuthorizedOrganizationUsageUseC
       timezone: input.timezone,
     })
     const bucket = resolveUsageBucket(window)
-    const scope = buildUsageAnalyticsScope(context.billingEntity, window)
+    const scope = buildUsageAnalyticsScope(context.billingEntity, window, input.workspaceId)
 
     /**
      * The comparison window only exists when it is exactly derivable.
@@ -68,7 +70,11 @@ export const getOrganizationUsageSummary = defineAuthorizedOrganizationUsageUseC
       readUsageTotals(scope),
       readUsageTimeSeries(scope, bucket, input.timezone),
       comparison
-        ? readUsageTotals(buildUsageAnalyticsScope(context.billingEntity, comparison))
+        ? readUsageTotals(
+            // Same narrowing as the current window, or the delta would compare one
+            // workspace against the whole organization.
+            buildUsageAnalyticsScope(context.billingEntity, comparison, input.workspaceId)
+          )
         : Promise.resolve(null),
     ])
 

apps/sim/lib/billing/application/organization-usage/organization-usage-use-cases.test.ts

@@ -125,4 +125,30 @@ describe('organization usage authorization', () => {
     expect(JSON.stringify(totalsScope)).toContain(ORG)
     expect(JSON.stringify(seriesScope)).toBe(JSON.stringify(totalsScope))
   })
+
+  it('narrows the drill-down’s chart and its comparison window to the same workspace', async () => {
+    /*
+      A reporting period, so the delta's read actually happens: `resolvePreviousPeriod`
+      returns null for a stripe period, and against the default subscription above this
+      test would assert the narrowing of a query that was never issued.
+    */
+    mocks.getOrganizationSubscription.mockResolvedValue({
+      plan: 'enterprise',
+      metadata: { reportingPeriodAnchorDate: '2026-01-01', reportingPeriodInterval: 'month' },
+    })
+
+    await getOrganizationUsageSummary.execute({
+      principal: session,
+      input: { ...input, workspaceId: 'ws-1' },
+    })
+
+    // The current window and the previous one, both narrowed. Narrowing only the
+    // current window measures one workspace against the whole organization and
+    // renders the difference as that workspace's own trend.
+    expect(mocks.readUsageTotals).toHaveBeenCalledTimes(2)
+    for (const [scope] of mocks.readUsageTotals.mock.calls) {
+      expect(JSON.stringify(scope)).toContain('ws-1')
+    }
+    expect(JSON.stringify(mocks.readUsageTimeSeries.mock.calls[0][0])).toContain('ws-1')
+  })
 })

apps/sim/lib/billing/core/usage-analytics-queries.ts

@@ -120,13 +120,10 @@ function breakdownColumn(dimension: UsageBreakdownDimension) {
 export async function readUsageBreakdown(
   scope: SQL[],
   dimension: UsageBreakdownDimension,
-  /** Narrows to one workspace, for the Workspaces drill-down. */
-  workspaceId: string | undefined,
   executor: DbClient = dbReplica
 ): Promise<UsageBreakdownRow[]> {
   const column = breakdownColumn(dimension)
   const conditions = [...scope]
-  if (workspaceId) conditions.push(eq(usageLog.workspaceId, workspaceId))
   /**
    * `description` holds a model name only for the model categories; a tool or fixed
    * row would otherwise appear as a phantom "model". The two model dimensions split

apps/sim/lib/billing/core/usage-analytics.test.ts

@@ -68,6 +68,33 @@ describe('buildUsageAnalyticsScope', () => {
     expect(shape).toContain('usageLog.billingEntityType')
     expect(shape).toContain('usageLog.billingEntityId')
   })
+
+  it('narrows to a workspace in every window shape', () => {
+    // Each branch returns its own array, so a narrowing added to only one of them is a
+    // drill-down that quietly reports the whole organization under the other two.
+    const windows = [
+      { kind: 'period', period: period({ source: 'stripe' }) },
+      {
+        kind: 'period',
+        period: period({ source: 'reporting', anchorDate: '2026-08-01', interval: 'month' }),
+      },
+      {
+        kind: 'range',
+        from: new Date('2026-08-01T00:00:00.000Z'),
+        to: new Date('2026-08-08T00:00:00.000Z'),
+      },
+    ] as const
+
+    for (const window of windows) {
+      expect(JSON.stringify(buildUsageAnalyticsScope(ENTITY, window, 'ws-1'))).toContain(
+        'usageLog.workspaceId'
+      )
+    }
+  })
+
+  it('leaves the scope organization-wide when no workspace is given', () => {
+    expect(scopeShape({ kind: 'period', period: period() })).not.toContain('usageLog.workspaceId')
+  })
 })
 
 describe('usageWindowLedgerFilter', () => {