Report Methodology

This document defines every calculated figure so managers can defend the numbers. The same definitions are embedded in the application (Settings → Scoring, user drill-down) and in every export (Methodology section / "Scoring Methodology" worksheet).

1. Data model

All usage is stored as daily metric values per user (or per organization) per product, exactly as delivered by the official sources:

• Claude Enterprise Analytics API (per-user activity, summaries, skills, usage & cost) — daily UTC snapshots
• Claude Code Analytics Admin API — daily UTC per-actor records
• Usage & Cost Admin API — daily UTC buckets
• Official CSV exports (imported)

Raw metrics are never modified; every derived figure is computed from them on demand. Source authority is official API > file import > demo, so an import can never overwrite API data.

Days are UTC calendar days as reported by Anthropic. Reporting periods (week/month/quarter/year/custom) are resolved in the configured organization timezone (default Asia/Phnom_Penh) and select whole UTC data days.

2. Weighted Usage Index (Total Usage %)

Raw values such as messages, tokens and lines of code are never summed together. Instead, each enabled metric m with weight w(m), target t(m) and contribution cap c(m):

attainment(m) = actual(m) / effective_target(m)
contribution(m) = w(m) × min(attainment(m), c(m))          # cap default 200%

Total Usage % = 100 × Σ contribution(m) ÷ Σ w(m)           # applicable m only

• Targets are defined per basis_days (default 30) and scaled linearly to the report period length (configurable). Example: target 200 messages / 30 days → 46.7 for a 7-day report.
• Active-day metrics (<product>.active_days) count distinct days with any activity for that product. When exclude weekends is enabled, active-day targets scale by countable working days (working_days(period) ÷ (basis_days × 5/7)), and configured public holidays are excluded from countable days.
• Contribution cap (default 200%, configurable per metric, minimum 100%): one extreme metric cannot mask non-use of other products. The uncapped attainment stays visible in the drill-down for transparency.
• Applicability: a metric enters the denominator only when its product's data is obtainable for the period — an available API capability or any imported official data. A category the plan does not provide is excluded, never treated as zero.
• No Data: a user with no applicable metrics at all has no score and is classified No Data (never 0%).
• Scores above 100% are expected when usage exceeds targets.

Sub-scores

The same formula restricted to a product family:

• Chat Usage % — metrics with product chat
• Claude Code Usage % — metrics with product claude_code
• Other Product Usage % — every other product (Cowork, Claude Design, Office Agent, Science, future products)

Share of Organization Activity

share(u) = 100 × Σ contribution_u(m) ÷ Σ over all users Σ contribution(m)

Shares sum to 100% across scored users.

Policy versioning

Weights/targets/caps/basis are stored as a versioned scoring policy. Any change creates a new version (audited). Because scores are always computed from raw metrics, historical periods automatically reflect the active policy; every report records the policy version used.

Default policy (v1)

Metric	Weight	Target / 30 days	Cap
Claude Chat — messages	25	200	200%
Claude Chat — conversations	10	40	200%
Claude Chat — active days	10	12	200%
Claude Chat — projects used	5	4	200%
Claude Chat — artifacts created	5	6	200%
Claude Code — sessions	15	20	200%
Claude Code — active days	10	8	200%
Claude Code — lines added	5	2000	200%
Claude Code — commits	5	10	200%
Cowork — sessions	5	8	200%
Claude Design — sessions	5	4	200%

Consumption metrics (tokens, cost, requests) are intentionally not scorable — they measure spend, not adoption — and are reported beside the score instead.

3. Usage status classification

Evaluated per user per period, in this order:

1. Exempt (policy) — membership states excluded by configuration (invited / disabled / removed / service accounts, all configurable).
2. Exempt — a matching active alert exemption (exact email, wildcard, domain, or group; within its start/expiry window). Exemption suppresses alerts only; exempt users stay in dashboards, reports and totals unless the explicit "exclude exempt from totals" report option is enabled.
3. Grace Period — joined within the configured grace window (default 14 days before period end).
4. No Data — no reliable data for the period.
5. Threshold bands (global or per-group override):
6. Passed: Total Usage % ≥ the passing threshold (default 50%)
7. Warning: ≥ warning threshold (default 20%) and < the passing threshold
8. Critical: < warning threshold
9. A passing score with fewer than the configured minimum active days downgrades to Warning (the reason says why).

Alerts are generated for Warning / Critical (and optionally No Data), with per-period dedupe and a configurable suppression window for repeats.

4. Organization KPIs

KPI	Definition
Assigned seats	Latest assigned_seat_count reported by the API; falls back to the count of active members (the source is always labeled)
Active users (period)	Users with ≥ 1 active day in the period
Inactive users	Active members with 0 active days in the period
Seat utilization	Active users ÷ assigned seats
Average / Median usage	Mean / median of Total Usage % over scored users
Low-usage users	Warning + Critical count
Tokens / Cost	Sum of user-attributed token counts / cost (Decimal math; API cents converted exactly)
Last activity / inactive days	Latest active data day per user; inactive days measured to the data-freshness date so missing data is not misread as inactivity

5. Consistency guarantee

Every report generation builds one snapshot (period + filters) and all selected formats — and the on-screen preview — render from that same snapshot object. The automated test suite asserts XLSX/JSON/CSV totals equal the snapshot totals.

6. Known measurement limitations

• Official data lags (≈1 day for engagement, up to 24 h for usage/cost) and recent days can be revised by Anthropic for a while; the sync re-fetches a configurable lookback window (default 7 days) and reports carry the data-freshness timestamp plus a stale-data warning.
• Distinct counts from the Analytics API use approximation (documented typical error < 2%).
• Claude Code usage routed through non-Anthropic clouds (e.g. Bedrock) is not reported by these APIs.
• API-key actors (non-human) in Claude Code data are tracked separately and never mapped to human users.