---
id: CAP-PFM-LLM-017
title: Show administrators their organization’s AI allowance
feature: FEAT-PFM-LLM-06
product_area: platform
module: llm
revision: 1
status: draft
product_intent: proposed
implementation_evidence: partially-observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-2'
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-7'
  - 'services-platform:docs/milestones/PLAT-M3-ai-usage-organization-page.md#D-2 (proposal)'
purpose: >-
  Give customer administrators a credit-based view of their own usage without disclosing internal commercial
  details.
outcomes:
  - The summary describes the organization’s credit position.
  - Availability entries explain feature restrictions.
  - Organization-scoped datasets support request and task reporting.
concepts:
  - CON-PFM-LLM-003
  - CON-PFM-LLM-004
actors:
  - ACT-PFM-007
surfaces:
  - console
  - api
preconditions: []
postconditions: []
permissions:
  - key: platform.llm-usage.read
    where_checked: api
    scope: tenant
rules:
  - id: BR-CAP-PFM-LLM-017-01
    proved_by: [ATS-PFM-LLM-017-01, TST-PFM-LLM-006]
    statement: >-
      The customer usage routes admit only console users in the organization with its usage key, excluding
      unkeyed, anonymous, foreign-customer and HQ-only callers.
    kind: permission
    enforced_at:
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#is refused to
      Rhythm staff holding every HQ key, because the routes are console
    origin: none
  - id: BR-CAP-PFM-LLM-017-02
    proved_by: [ATS-PFM-LLM-007-19, ATS-PFM-LLM-017-02, ATS-PFM-LLM-017-11, TST-PFM-LLM-051]
    statement: >-
      The summary contains the current allowance, charged-plus-held usage, remaining credits, percentage,
      within or warned or limited status, local reset date and zone, AI switch, explanatory messages,
      six-month history and usage by feature.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage/organization-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-017-03
    proved_by: [ATS-PFM-LLM-017-03, ATS-PFM-LLM-017-12, TST-PFM-LLM-006, TST-PFM-LLM-083]
    statement: >-
      Customer usage summaries expose credits and percentages while withholding money, providers, models,
      prices, capacity grants and internal limits.
    kind: policy
    enforced_at:
      - service
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#carries no key
      naming money, a provider, a model, an override or a limit on the summary
    origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-7'
  - id: BR-CAP-PFM-LLM-017-04
    proved_by: [ATS-PFM-LLM-013-11, ATS-PFM-LLM-017-04, ATS-PFM-LLM-017-13, TST-PFM-LLM-006, TST-PFM-LLM-051, TST-PFM-LLM-084]
    statement: >-
      The feature list supplies labels, descriptions and availability; disabled AI or all disabled operations
      takes explanatory precedence over exhausted allowance.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage/organization-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-017-05
    proved_by: [ATS-PFM-LLM-017-05]
    statement: >-
      Active exemptions are ignored by the customer feature list, so it can label an operation restricted even
      though admission permits its request.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage/organization-usage.ts:restrictionOf'
    origin: none
  - id: BR-CAP-PFM-LLM-017-06
    proved_by: [ATS-PFM-LLM-017-06, TST-PFM-LLM-051]
    statement: >-
      Declared operations group under their catalog feature and undeclared historical operations group under
      Other AI features.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/usage/organization-usage.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-017-07
    proved_by: [ATS-PFM-LLM-017-07, TST-PFM-LLM-051]
    statement: Customer usage reads stay within the organization’s own periods.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/services/usage/organization-usage.integration.spec.js#does
      not read another organization’s period
    origin: none
  - id: BR-CAP-PFM-LLM-017-08
    proved_by: [ATS-PFM-LLM-017-08, TST-PFM-LLM-013]
    statement: >-
      The usage key also supports local request and task query recipes by period, feature, person and problem
      outcome; reporting excludes content, storage, refusal snapshots, raw usage and pricing versions and uses
      UTC reporting dates.
    kind: permission
    enforced_at:
      - database
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/db/llm-invocations-query.view.integration.spec.js#offers
      none of the evidence, payload, refusal, usage or version columns
    origin: none
  - id: BR-CAP-PFM-LLM-017-09
    proved_by: [ATS-PFM-LLM-017-09]
    statement: >-
      The product should provide the approved dashboard with credits, reset date, feature states, six-month
      history, pause explanation and request-history navigation without internal money, model or control
      detail.
    kind: policy
    enforced_at:
      - console
    must_prove: true
    provenance: documented
    source: 'services-platform:docs/milestones/PLAT-M3-ai-usage-organization-page.md#Scope in one paragraph'
    origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-2'
scenarios:
  - id: SC-CAP-PFM-LLM-017-01
    given: The organization is near its allowance threshold.
    when: An administrator requests its summary.
    then: 'The response includes the credit position, warning status, local reset date and descending history.'
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/services/usage/organization-usage.integration.spec.js#resets
      on the first of next month in the organization’s own calendar
  - id: SC-CAP-PFM-LLM-017-02
    given: Rhythm disables the query operation.
    when: An administrator requests feature availability.
    then: The query feature carries the corresponding restriction explanation.
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/services/usage/organization-usage.integration.spec.js#restricts
      the feature, with the sentence, once its operation is turned off for the organization
edge_cases: []
constraints:
  - The summary services and reporting datasets exist; the planned customer page is absent.
depends_on:
  - CAP-PFM-LLM-007
  - CAP-PFM-LLM-013
related:
  - CAP-PFM-LLM-018
journeys:
  - JNY-PFM-LLM-004
open_questions:
  - OQ-PFM-LLM-001
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (What an organization sees,
    Reporting); docs/milestones/PLAT-M3-ai-usage-organization-page.md; aws/api/llm-usage.routes.ts
    (getLlmUsageSummary, listLlmUsageFeatures); aws/platform.service.ts (LLM_USAGE_PERMISSIONS);
    services/usage/organization-usage.ts, usage-features.ts; db/llm-invocations-query.view.ts; tests
    e2e/llm-adjustments-and-organization.e2e.spec.js,
    integration/services/usage/organization-usage.integration.spec.js,
    integration/db/llm-invocations-query.view.integration.spec.js,
    unit/services/usage/organization-usage.spec.ts.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/nav-config.ts (Dashboards
    entry planned only); no organization AI Usage page found.
controls: [TC-AVL-001, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, 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-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-LLM-06-01, FAS-PFM-LLM-06-02, FAS-PFM-LLM-06-03, FAS-PFM-LLM-06-04, FAS-PFM-LLM-06-05]
suites: [TST-PFM-LLM-006, TST-PFM-LLM-013, TST-PFM-LLM-051, TST-PFM-LLM-083, TST-PFM-LLM-084]
---

# Show administrators their organization’s AI allowance

## Purpose

Give customer administrators a credit-based view of their own usage without disclosing internal commercial details.

## How It Works

An administrator uses the organization-scoped usage service to read its current allowance position. The summary combines charged and held credits with remaining capacity and the reset date. It also groups usage by feature and supplies recent monthly history. Feature availability explains disabled AI or exhausted capacity. The current feature-list implementation omits active operation exemptions and can disagree with admission. Queries expose the organization’s request and task reporting data under the same usage authority. Internal money, model and control details stay out of the customer summary. The product should deliver the approved dashboard and resolve its availability mismatch before asking customers to rely on it.

## Relationships

- Admit AI work against the organization’s monthly allowance supplies the prerequisite behavior for this outcome.
- Set an organization’s AI access and recurring limits supplies the prerequisite behavior for this outcome.