---
id: SCR-PFM-LLM-003
title: Rhythm HQ AI Usage dashboard
route: /hq/aiUsage
surface: console
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
purpose: Inspect historical AI cost and current allowance concerns across organizations.
supports:
  - JNY-PFM-LLM-002
  - CAP-PFM-LLM-010
  - CAP-PFM-LLM-005
permission: hq.llm-usage.read (every HQ reader role holds it); others see a permission-denied panel
entry_from:
  - The existing navigation entry or its recorded planned placement.
exits_to:
  - SCR-PFM-LLM-004 (requests of an organization)
  - SCR-PFM-LLM-007 (an organization's AI Usage card)
displays:
  - field: 'Comparative cost, activity, warning, stop and latency tiles'
    source: 'getHqLlmUsageSummary and getHqLlmUsageBreakdown (by model, for latency)'
  - field: Spend trend for the selected reporting dimension
    source: getHqLlmUsageTrend
  - field: Current attention organizations and high-cost operations
    source: listHqLlmUsageTenants and getHqLlmUsageBreakdown
  - field: Paged organization history with available live capacity
    source: listHqLlmUsageTenants
  - field: 'Grouped model, provider, application, feature and operation totals'
    source: getHqLlmUsageBreakdown
  - field: Published operation routing and model-price history
    source: getHqLlmUsageCatalog and getHqLlmUsageRates
actions:
  - label: 'Period (month to date, last thirty days, last ninety days)'
    operation_id: 'none: re-reads every section for the window'
    permission: hq.llm-usage.read
    confirm: false
  - label: Search organizations
    operation_id: 'none: narrows the loaded page in the console'
    permission: hq.llm-usage.read
    confirm: false
  - label: Load more organizations
    operation_id: listHqLlmUsageTenants
    permission: hq.llm-usage.read
    confirm: false
states:
  - 'loading: cards fetch independently'
  - 'error: the affected card offers retry'
  - 'empty: cards distinguish absent spend, organizations and operations'
  - 'read-only: reporting performs no control mutation'
  - 'permission denied: the page withholds usage sections'
validation:
  - BR-CAP-PFM-LLM-010-01
  - BR-CAP-PFM-LLM-010-10
  - BR-CAP-PFM-LLM-010-11
patterns:
  - Standard layout (PageLayout with PageHeader and a period filter)
  - Staff-only HQ page guard
  - 'HQ card header and card states (loading, error with retry, empty)'
  - Money shown as dollars with credits beside
component: components/console/hq/ai-usage/ai-usage-dashboard.tsx and its cards
evidence:
  - >-
    react-console at baf6dae: app/(console)/hq/aiUsage/page.tsx;
    components/console/hq/ai-usage/ai-usage-dashboard.tsx, ai-usage-tiles.tsx, ai-usage-trend-card.tsx,
    needs-attention-card.tsx, top-operations-card.tsx, organizations-card.tsx, breakdowns-card.tsx,
    catalog-card.tsx; lib/hq/ai-usage.ts, ai-usage-format.ts, permissions.ts;
    e2e/mock/hq-ai-usage.mock.spec.ts.
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Rhythm HQ AI Usage dashboard

## What the Screen Is For

Rhythm staff use the dashboard to compare model activity, investigate expensive operations and identify organizations close to their allowance.

## What It Shows and Lets People Do

The period selects historical summaries, trend, attention list, organization table and breakdowns. Catalogue history is a separate read. The organization table filters loaded results locally and loads further pages on request. Links lead to organization usage and request investigation. No costliest-task card is rendered here.

## States and Errors

Sections load and fail independently and offer their own retry or empty states. Staff-only presentation and usage-read authority gate the page. Historical totals follow rollup progress; current positions come from separate live reads.

## Patterns It Must Respect

PageLayout and PageHeader host the period selector and existing HQ cards. Readable status labels and monetary formatting show dollars with credits beside.