---
id: CAP-PFM-LLM-011
title: Inspect an organization’s AI account and request history
feature: FEAT-PFM-LLM-04
product_area: platform
module: llm
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/milestones/plans/PLAT-M1-plan.md#4. Assumptions'
purpose: >-
  Let support staff connect an organization’s current allowance position with the requests and controls behind
  it.
outcomes:
  - Support inspects an organization’s AI position from HQ.
  - Request details expose metadata and attempts separately from captured bodies.
  - 'Control history retains limits, grants, corrections and notices.'
concepts:
  - CON-PFM-LLM-003
  - CON-PFM-LLM-001
  - CON-PFM-LLM-004
actors:
  - ACT-PFM-033
  - ACT-PFM-004
surfaces:
  - console
  - api
preconditions:
  - An existing organization is selected.
postconditions: []
permissions:
  - key: hq.llm-usage.read
    where_checked: api
    scope: global
  - key: hq.llm-usage.read
    where_checked: console
    scope: global
  - key: hq.llm-usage.manage
    where_checked: console
    scope: global
rules:
  - id: BR-CAP-PFM-LLM-011-01
    proved_by: [ATS-PFM-LLM-011-01, TST-PFM-LLM-009]
    statement: >-
      The HQ usage read key authorizes organization usage inspection for Rhythm staff, while a customer
      administrator cannot use that surface even for their own organization.
    kind: permission
    enforced_at:
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-usage.e2e.spec.js#refuses a customer’s administrator a
      tenant’s usage even in their own tenant
    origin: none
  - id: BR-CAP-PFM-LLM-011-02
    proved_by: [ATS-PFM-LLM-010-09, ATS-PFM-LLM-011-02, ATS-PFM-LLM-011-15, TST-PFM-LLM-009, TST-PFM-LLM-033, TST-PFM-LLM-050]
    statement: >-
      Reads first resolve the named organization and scope its records accordingly, returning not found for
      nonexistent organizations or foreign requests and executions.
    kind: validation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-usage.e2e.spec.js#answers 404 for a request of another
      tenant, the tenant policy binding the read
    origin: none
  - id: BR-CAP-PFM-LLM-011-03
    proved_by: [ATS-PFM-LLM-007-14, ATS-PFM-LLM-011-03, ATS-PFM-LLM-011-10, ATS-PFM-LLM-011-14, ATS-PFM-LLM-011-18, TST-PFM-LLM-001, TST-PFM-LLM-004, TST-PFM-LLM-050]
    statement: >-
      The overview independently reports the current allowance position, configured or default limits, active
      capacity, six recent periods, operation and model totals and twenty recent problem requests.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-04
    proved_by: [ATS-PFM-LLM-011-04, TST-PFM-LLM-050]
    statement: >-
      Historical periods evaluate capacity at their last instant and the current period evaluates it now;
      ended and revoked grants do not count as currently active.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-05
    proved_by: [ATS-PFM-LLM-011-05, ATS-PFM-LLM-011-16, ATS-PFM-LLM-011-17, TST-PFM-LLM-009, TST-PFM-LLM-035, TST-PFM-LLM-052]
    statement: >-
      The request directory is newest-first and supports period or date windows and operation, model, status,
      execution and caller filters, with at most one hundred rows per page and rejection of invalid filters or
      cursors.
    kind: validation
    enforced_at:
      - api
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-06
    proved_by: [ATS-PFM-LLM-011-06, ATS-PFM-LLM-011-09, ATS-PFM-LLM-011-13, TST-PFM-LLM-002, TST-PFM-LLM-009]
    statement: >-
      Usage lists and details withhold captured bodies and storage references, exposing only their capture
      status.
    kind: invariant
    enforced_at:
      - api
      - service
      - console
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-07
    proved_by: []
    statement: >-
      Request detail identifies the caller, feature, routing, charge, ordered attempts, pricing versions,
      execution and any retained refusal figures.
    kind: policy
    enforced_at:
      - api
      - console
    must_prove: false
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:toInvocationDetailResponse'
    origin: none
  - id: BR-CAP-PFM-LLM-011-08
    proved_by: [ATS-PFM-LLM-003-09]
    statement: >-
      Organization execution lists include running tasks, and each detail pairs the task totals with its
      associated requests.
    kind: policy
    enforced_at:
      - api
    must_prove: false
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-09
    proved_by: [ATS-PFM-LLM-011-07, ATS-PFM-LLM-011-11, TST-PFM-LLM-009, TST-PFM-LLM-029]
    statement: >-
      Grant lists order by newest start and derive scheduled, active, expired or revoked state at read time,
      optionally showing active grants only.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/services/overrides/allowance-overrides.integration.spec.js#answers
      each override with the state it has now, newest start first
    origin: none
  - id: BR-CAP-PFM-LLM-011-10
    proved_by: [ATS-PFM-LLM-008-11]
    statement: >-
      Limit reads distinguish defaults from configuration and show ceilings, correction reads preserve signed
      values, and crossing reads expose delivery time, attempt count and recipient count.
    kind: policy
    enforced_at:
      - api
    must_prove: false
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-11
    proved_by: [ATS-PFM-LLM-011-12]
    statement: >-
      The AI audit trail filters this organization’s limit, grant, revocation, correction and content-read
      events and orders them newest-first.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-011-12
    proved_by: [ATS-PFM-LLM-011-08, TST-PFM-LLM-002]
    statement: >-
      Support readers receive no usage action menu or write controls, while staff with management authority
      receive the action menu.
    kind: permission
    enforced_at:
      - console
    must_prove: true
    provenance: test
    source: >-
      react-console:e2e/mock/hq-ai-usage.mock.spec.ts#a Support Representative reads the card but has no
      action menu and no write controls
    origin: none
scenarios:
  - id: SC-CAP-PFM-LLM-011-01
    given: A limited organization is opened in HQ.
    when: Support reads its usage card.
    then: 'The card renders allowance and reset figures, default limits, history and refusals.'
    provenance: test
    source: >-
      react-console:e2e/mock/hq-ai-usage.mock.spec.ts#reads the limited organization: the warning band, the
      limits, the history and the refusals
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-LLM-007
related:
  - CAP-PFM-LLM-003
  - CAP-PFM-LLM-008
  - CAP-PFM-LLM-010
  - CAP-PFM-LLM-012
  - CAP-PFM-LLM-013
  - CAP-PFM-LLM-014
  - CAP-PFM-LLM-015
  - CAP-PFM-LLM-016
journeys:
  - JNY-PFM-LLM-002
open_questions: []
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (One tenant);
    modules/llm/README.md; aws/api/llm-usage.routes.ts (getHqTenantLlmUsage, listHqTenantLlmUsagePeriods,
    listHqTenantLlmUsageInvocations, getHqTenantLlmUsageInvocation, listHqTenantLlmUsageExecutions,
    getHqTenantLlmUsageExecution, getHqTenantLlmUsageLimits, listHqTenantLlmUsageOverrides,
    listHqTenantLlmUsageAdjustments, listHqTenantLlmUsageCrossings, listHqTenantLlmUsageAudit);
    services/usage-reports/tenant-usage.ts, executions.ts, period-allowances.ts, audit-trail.ts;
    services/persistence/*.ts; tests e2e/llm-usage.e2e.spec.js,
    integration/services/usage-reports/tenant-usage.integration.spec.js,
    integration/services/persistence/*.queries.integration.spec.js.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: app/(console)/hq/tenants/[id]/page.tsx;
    components/console/hq/tenant-ai-usage-card.tsx, tenant-ai-usage-section.tsx;
    app/(console)/hq/aiUsage/requests/**, executions/**; components/console/hq/ai-usage/ai-usage-requests.tsx,
    ai-usage-request-detail.tsx, ai-usage-execution-detail.tsx, request/*; lib/hq/ai-usage.ts,
    ai-usage-audit.ts, permissions.ts; e2e/mock/hq-ai-usage.mock.spec.ts; lib/hq/ai-usage.test.ts.
controls: [TC-AI-006, TC-AI-007, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-003, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-LLM-04-01, FAS-PFM-LLM-04-02, FAS-PFM-LLM-04-03, FAS-PFM-LLM-04-04, FAS-PFM-LLM-04-05]
suites: [TST-PFM-LLM-001, TST-PFM-LLM-002, TST-PFM-LLM-004, TST-PFM-LLM-009, TST-PFM-LLM-029, TST-PFM-LLM-033, TST-PFM-LLM-035, TST-PFM-LLM-050, TST-PFM-LLM-052]
---

# Inspect an organization’s AI account and request history

## Purpose

Let support staff connect an organization’s current allowance position with the requests and controls behind it.

## How It Works

A staff reader opens the organization’s AI Usage card. Its independent sections combine the current period with limits, active capacity and recent history. The reader can open the request directory and narrow it to the work they need to investigate. Request details provide attribution, attempts and the versions used for pricing. Execution details group the model requests belonging to one task. Separate lists expose grants, corrections, crossings and AI audit events. Ordinary reads show content status while keeping captured bodies behind their separate access boundary. The support role remains read-only, and authorized managers see the currently disabled action menu.

## Relationships

- Admit AI work against the organization’s monthly allowance supplies the prerequisite behavior for this outcome.