- Daily {metric === "tokens" ? "processed tokens" : "cost"}
+ Daily{" "}
+ {metric === "tokens"
+ ? "processed tokens"
+ : merged.costQuality.unpricedShare > 0
+ ? "cost (partial)"
+ : "cost"}
@@ -269,94 +259,12 @@ export function UsagePage() {
- {breakdown === "model" ? (
-
-
-
- | Model |
- Cost |
- Share |
- Tokens |
-
-
-
- {merged.models.length === 0 ? (
-
- |
- No activity in this window.
- |
-
- ) : (
- merged.models.map((model) => (
-
- |
-
-
- {model.model}
-
- |
-
- {formatUsd(model.costUsd)}
- |
-
- {formatPercent(model.costShare)}
- |
-
- {formatTokens(model.totalTokens)}
- |
-
- ))
- )}
-
-
- ) : (
-
-
-
- | Day |
- {PROVIDER_ORDER.map((provider) => (
-
- {PROVIDER_LABEL[provider]}
- |
- ))}
- Total |
- Tokens |
-
-
-
- {recentDays.length === 0 ? (
-
- |
- No activity in this window.
- |
-
- ) : (
- recentDays.map((day) => (
-
- | {formatDayShort(day.day)} |
- {PROVIDER_ORDER.map((provider) => (
-
- {formatUsd(day.byProvider.get(provider)?.costUsd ?? 0)}
- |
- ))}
-
- {formatUsd(day.costUsd)}
- |
-
- {formatTokens(day.totalTokens)}
- |
-
- ))
- )}
-
-
- )}
+
)}
@@ -365,6 +273,190 @@ export function UsagePage() {
);
}
+/** Provider totals and share bars for the selected chart metric. */
+export function UsageProviderRows({
+ providers,
+ metric,
+ totalUnpricedShare,
+}: {
+ readonly providers: readonly ProviderTotals[];
+ readonly metric: UsageChartMetric;
+ readonly totalUnpricedShare: number;
+}) {
+ return providers.map((provider) => {
+ const share = metric === "cost" ? provider.costShare : provider.tokenShare;
+ const providerCost = formatCostEstimate(provider.costUsd, provider.unpricedShare);
+ const costShareLabel = totalUnpricedShare > 0 ? "priced cost" : "cost";
+ const costShareText =
+ provider.unpricedShare >= 1
+ ? "No priced-cost share"
+ : `${formatPercent(share)} of ${costShareLabel}`;
+ return (
+
+
+
+
+ {PROVIDER_LABEL[provider.provider]}
+
+
+ {metric === "cost" ? providerCost.value : formatTokens(provider.totalTokens)}
+
+
+
+
+ {metric === "cost"
+ ? `${costShareText}${provider.unpricedShare > 0 ? ` · ${formatPercent(provider.unpricedShare)} unpriced` : ""} · ${formatTokens(provider.totalTokens)} tokens`
+ : `${formatPercent(share)} of tokens · ${providerCost.value}`}
+
+
+ );
+ });
+}
+
+const COST_GUIDANCE_ID = "usage-cost-guidance";
+
+/** Model/day details with a shared, screen-reader-addressable pricing guide. */
+export function UsageBreakdownTable({
+ breakdown,
+ models,
+ recentDays,
+ totalUnpricedShare,
+}: {
+ readonly breakdown: "model" | "day";
+ readonly models: readonly ModelTotals[];
+ readonly recentDays: readonly DailyTotals[];
+ readonly totalUnpricedShare: number;
+}) {
+ const hasUnpriced = totalUnpricedShare > 0;
+ const describedBy = hasUnpriced ? COST_GUIDANCE_ID : undefined;
+
+ return (
+ <>
+ {hasUnpriced ? (
+
+ Cost guide: ≥ means a lower-bound estimate from matching API rates; — means no matching
+ rate. Token totals remain complete.
+
+ ) : null}
+
+ {breakdown === "model" ? (
+
+
+
+ | Model |
+ Cost |
+
+ {hasUnpriced ? "Share of priced cost" : "Share"}
+ |
+ Tokens |
+
+
+
+ {models.length === 0 ? (
+
+ |
+ No activity in this window.
+ |
+
+ ) : (
+ models.map((model) => {
+ const modelCost = formatCostEstimate(model.costUsd, model.unpricedShare);
+ return (
+
+ |
+
+
+ {model.model}
+
+ |
+
+ {modelCost.value}
+ |
+
+ {model.unpricedShare >= 1 ? "—" : formatPercent(model.costShare)}
+ |
+
+ {formatTokens(model.totalTokens)}
+ |
+
+ );
+ })
+ )}
+
+
+ ) : (
+
+
+
+ | Day |
+ {PROVIDER_ORDER.map((provider) => (
+
+ {PROVIDER_LABEL[provider]}
+ |
+ ))}
+ Total |
+ Tokens |
+
+
+
+ {recentDays.length === 0 ? (
+
+ |
+ No activity in this window.
+ |
+
+ ) : (
+ recentDays.map((day) => (
+
+ | {formatDayShort(day.day)} |
+ {PROVIDER_ORDER.map((provider) => {
+ const providerDay = day.byProvider.get(provider);
+ return (
+
+ {providerDay === undefined ? (
+ —
+ ) : (
+
+ )}
+ |
+ );
+ })}
+
+
+ |
+
+ {formatTokens(day.totalTokens)}
+ |
+
+ ))
+ )}
+
+
+ )}
+
+ );
+}
+
/** Brand mark for the harness a row belongs to. */
function ProviderMark({
provider,
@@ -395,6 +487,17 @@ function Metric({
);
}
+function CostAmount({
+ costUsd,
+ unpricedShare,
+}: {
+ readonly costUsd: number;
+ readonly unpricedShare: number;
+}) {
+ const estimate = formatCostEstimate(costUsd, unpricedShare);
+ return
{estimate.value};
+}
+
/**
* Says plainly when the totals are incomplete: an environment that failed, or
* one whose transcripts another environment already reported. Environments
diff --git a/apps/web/src/components/usage/UsageProviderChart.test.ts b/apps/web/src/components/usage/UsageProviderChart.test.ts
index a36cd1e88330..ba776a29c1bb 100644
--- a/apps/web/src/components/usage/UsageProviderChart.test.ts
+++ b/apps/web/src/components/usage/UsageProviderChart.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vite-plus/test";
-import { buildDayColumns, niceScale } from "./UsageProviderChart";
+import { buildDayColumns, formatChartValue, niceScale } from "./UsageProviderChart";
describe("niceScale", () => {
it("never puts the peak above the top of the scale", () => {
@@ -49,9 +49,10 @@ describe("buildDayColumns", () => {
day: "2026-08-01",
costUsd: 30,
totalTokens: 300,
+ unpricedShare: 0.5,
byProvider: new Map([
- ["codex" as const, { costUsd: 10, totalTokens: 100 }],
- ["claude" as const, { costUsd: 20, totalTokens: 200 }],
+ ["codex" as const, { costUsd: 10, totalTokens: 100, unpricedShare: 1 }],
+ ["claude" as const, { costUsd: 20, totalTokens: 200, unpricedShare: 0.25 }],
]),
},
],
@@ -62,7 +63,10 @@ describe("buildDayColumns", () => {
day: "2026-08-03",
costUsd: 5,
totalTokens: 50,
- byProvider: new Map([["claude" as const, { costUsd: 5, totalTokens: 50 }]]),
+ unpricedShare: 0,
+ byProvider: new Map([
+ ["claude" as const, { costUsd: 5, totalTokens: 50, unpricedShare: 0 }],
+ ]),
},
],
]);
@@ -77,14 +81,45 @@ describe("buildDayColumns", () => {
]);
});
+ it("retains pricing coverage for cost hover values", () => {
+ const [first] = buildDayColumns(days, byDay, "cost");
+
+ expect(first).toMatchObject({
+ unpricedShare: 0.5,
+ bands: [
+ { provider: "codex", unpricedShare: 1 },
+ { provider: "claude", unpricedShare: 0.25 },
+ ],
+ });
+ });
+
+ it("retains whether sparse provider-day columns have activity", () => {
+ const columns = buildDayColumns(days, byDay, "cost");
+
+ expect(columns[1]).toMatchObject({
+ hasActivity: false,
+ bands: [
+ { provider: "codex", hasActivity: false },
+ { provider: "claude", hasActivity: false },
+ ],
+ });
+ expect(columns[2]).toMatchObject({
+ hasActivity: true,
+ bands: [
+ { provider: "codex", hasActivity: false },
+ { provider: "claude", hasActivity: true },
+ ],
+ });
+ });
+
it("keeps band values absolute rather than cumulative", () => {
// Regression: the bands were once stack offsets, which drew Claude Code
// permanently above Codex regardless of which provider spent more.
const [first] = buildDayColumns(days, byDay, "cost");
expect(first?.bands).toEqual([
- { provider: "codex", value: 10 },
- { provider: "claude", value: 20 },
+ { provider: "codex", value: 10, unpricedShare: 1, hasActivity: true },
+ { provider: "claude", value: 20, unpricedShare: 0.25, hasActivity: true },
]);
});
@@ -95,3 +130,20 @@ describe("buildDayColumns", () => {
}
});
});
+
+describe("formatChartValue", () => {
+ it("labels an inactive provider-day as no activity rather than priced zero", () => {
+ expect(formatChartValue("cost", 0, 0, false)).toBe("—");
+ expect(formatChartValue("cost", 0, 0, true)).toBe("$0.00");
+ });
+
+ it("does not show missing or partial cost rates as exact hover values", () => {
+ expect(formatChartValue("cost", 0, 1, true)).toBe("—");
+ expect(formatChartValue("cost", 20, 0.25, true)).toBe("≥$20.00");
+ expect(formatChartValue("cost", 20, 0, true)).toBe("$20.00");
+ });
+
+ it("keeps token hover values independent of pricing coverage", () => {
+ expect(formatChartValue("tokens", 20_000, 1, true)).toBe("20K");
+ });
+});
diff --git a/apps/web/src/components/usage/UsageProviderChart.tsx b/apps/web/src/components/usage/UsageProviderChart.tsx
index 8f31d348eb04..99ef673bfe65 100644
--- a/apps/web/src/components/usage/UsageProviderChart.tsx
+++ b/apps/web/src/components/usage/UsageProviderChart.tsx
@@ -2,7 +2,12 @@ import type { UsageProviderKind } from "@t3tools/contracts";
import { useCallback, useMemo, useRef, useState } from "react";
import type { DailyTotals } from "@t3tools/shared/usageMerge";
-import { formatDayShort, formatTokens, formatUsd } from "@t3tools/shared/usageFormat";
+import {
+ formatCostEstimate,
+ formatDayShort,
+ formatTokens,
+ formatUsd,
+} from "@t3tools/shared/usageFormat";
import { PROVIDER_COLOR, PROVIDER_LABEL, PROVIDER_MARK, PROVIDER_ORDER } from "./usageProviders";
const VIEW_WIDTH = 960;
@@ -12,6 +17,17 @@ const PLOT_TOP = 8;
export type UsageChartMetric = "tokens" | "cost";
+/** Formats a plotted value with the pricing coverage carried by its day column. */
+export function formatChartValue(
+ metric: UsageChartMetric,
+ value: number,
+ unpricedShare: number,
+ hasActivity: boolean,
+): string {
+ if (metric === "cost" && !hasActivity) return "—";
+ return metric === "tokens" ? formatTokens(value) : formatCostEstimate(value, unpricedShare).value;
+}
+
interface UsageProviderChartProps {
readonly days: readonly string[];
readonly daily: readonly DailyTotals[];
@@ -23,8 +39,12 @@ export interface DayColumn {
readonly bands: readonly {
readonly provider: UsageProviderKind;
readonly value: number;
+ readonly unpricedShare: number;
+ readonly hasActivity: boolean;
}[];
readonly total: number;
+ readonly unpricedShare: number;
+ readonly hasActivity: boolean;
}
interface Point {
@@ -172,8 +192,15 @@ export function buildDayColumns(
const bands = PROVIDER_ORDER.map((provider) => ({
provider,
value: valueFor(entry, provider, metric),
+ unpricedShare: entry?.byProvider.get(provider)?.unpricedShare ?? 0,
+ hasActivity: entry?.byProvider.has(provider) ?? false,
}));
- return { bands, total: bands.reduce((sum, band) => sum + band.value, 0) };
+ return {
+ bands,
+ total: bands.reduce((sum, band) => sum + band.value, 0),
+ unpricedShare: entry?.unpricedShare ?? 0,
+ hasActivity: entry !== undefined,
+ };
});
}
@@ -336,6 +363,7 @@ export function UsageProviderChart({ days, daily, metric }: UsageProviderChartPr
{formatDayShort(hoveredDay)}
{PROVIDER_ORDER.map((provider) => {
const Mark = PROVIDER_MARK[provider];
+ const band = hoveredColumn?.bands.find((entry) => entry.provider === provider);
return (
@@ -343,8 +371,11 @@ export function UsageProviderChart({ days, daily, metric }: UsageProviderChartPr
{PROVIDER_LABEL[provider]}
- {format(
- hoveredColumn?.bands.find((band) => band.provider === provider)?.value ?? 0,
+ {formatChartValue(
+ metric,
+ band?.value ?? 0,
+ band?.unpricedShare ?? 0,
+ band?.hasActivity ?? false,
)}
@@ -353,7 +384,12 @@ export function UsageProviderChart({ days, daily, metric }: UsageProviderChartPr
Total
- {format(hoveredColumn?.total ?? 0)}
+ {formatChartValue(
+ metric,
+ hoveredColumn?.total ?? 0,
+ hoveredColumn?.unpricedShare ?? 0,
+ hoveredColumn?.hasActivity ?? false,
+ )}
diff --git a/packages/shared/src/usageFormat.test.ts b/packages/shared/src/usageFormat.test.ts
new file mode 100644
index 000000000000..4fb0f88ff0c0
--- /dev/null
+++ b/packages/shared/src/usageFormat.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { formatCostEstimate } from "./usageFormat.js";
+
+describe("formatCostEstimate", () => {
+ it("does not present fully unpriced usage as zero cost", () => {
+ expect(formatCostEstimate(0, 1)).toEqual({
+ value: "—",
+ detail: "No matching API rates; token totals are still complete.",
+ });
+ });
+
+ it("marks a mixed priced and unpriced total as a lower bound", () => {
+ expect(formatCostEstimate(12.34, 0.25)).toEqual({
+ value: "≥$12.34",
+ detail: "Partial API-rate estimate; 25.0% of requests have no matching rate.",
+ });
+ });
+
+ it("keeps the existing API-rate label when every request is priced", () => {
+ expect(formatCostEstimate(12.34, 0)).toEqual({
+ value: "$12.34",
+ detail: "If billed at full API rate.",
+ });
+ });
+});
diff --git a/packages/shared/src/usageFormat.ts b/packages/shared/src/usageFormat.ts
index 21e11fee743d..2a8651c7a352 100644
--- a/packages/shared/src/usageFormat.ts
+++ b/packages/shared/src/usageFormat.ts
@@ -19,6 +19,29 @@ export function formatUsd(value: number): string {
return CURRENCY.format(value);
}
+/** Marks incomplete API-rate estimates without making missing prices look free. */
+export function formatCostEstimate(
+ costUsd: number,
+ unpricedShare: number,
+): { readonly value: string; readonly detail: string } {
+ if (unpricedShare >= 1) {
+ return {
+ value: "—",
+ detail: "No matching API rates; token totals are still complete.",
+ };
+ }
+ if (unpricedShare > 0) {
+ return {
+ value: `≥${formatUsd(costUsd)}`,
+ detail: `Partial API-rate estimate; ${formatPercent(unpricedShare)} of requests have no matching rate.`,
+ };
+ }
+ return {
+ value: formatUsd(costUsd),
+ detail: "If billed at full API rate.",
+ };
+}
+
export function formatCount(value: number): string {
return INTEGER.format(Math.round(value));
}
diff --git a/packages/shared/src/usageMerge.test.ts b/packages/shared/src/usageMerge.test.ts
index 3c377a33f97e..93305333134d 100644
--- a/packages/shared/src/usageMerge.test.ts
+++ b/packages/shared/src/usageMerge.test.ts
@@ -187,6 +187,12 @@ describe("mergeUsage", () => {
expect(merged.providers[0]?.costShare).toBeCloseTo(0.75, 5);
expect(merged.costQuality.unpricedShare).toBeCloseTo(0.5, 5);
expect(merged.costQuality.cacheSavingsUsd).toBe(4);
+ expect(merged.providers.find((provider) => provider.provider === "codex")?.unpricedShare).toBe(
+ 1,
+ );
+ expect(merged.models.find((model) => model.model === "gpt-5.6-sol")?.unpricedShare).toBe(1);
+ expect(merged.daily[0]?.unpricedShare).toBeCloseTo(0.5, 5);
+ expect(merged.daily[0]?.byProvider.get("codex")?.unpricedShare).toBe(1);
});
it("keeps two machines apart when hostname and home path collide", () => {
diff --git a/packages/shared/src/usageMerge.ts b/packages/shared/src/usageMerge.ts
index fd73c0a31c02..51c0687d5c67 100644
--- a/packages/shared/src/usageMerge.ts
+++ b/packages/shared/src/usageMerge.ts
@@ -27,6 +27,7 @@ export interface ProviderTotals {
readonly records: number;
readonly costShare: number;
readonly tokenShare: number;
+ readonly unpricedShare: number;
}
export interface ModelTotals {
@@ -36,13 +37,18 @@ export interface ModelTotals {
readonly totalTokens: number;
readonly records: number;
readonly costShare: number;
+ readonly unpricedShare: number;
}
export interface DailyTotals {
readonly day: string;
readonly costUsd: number;
readonly totalTokens: number;
- readonly byProvider: ReadonlyMap