# Run receipt

What one run cost and where it went: per model (input, output and cached tokens, cost), tool calls, and any other figures the app measures. Every figure is the service's own measure; while the run is going the total is labelled "so far". A cost that wasn't measured says so: with no measured model cost the total reads "Not measured", and when only some models have a cost the total is labelled partial. It is never shown as $0.00. When your server decides what's exact and what's a guess, give `totalText` and each model's `costText`, and they're shown as written.

- Registry name: `run-receipt` (`@candor/run-receipt`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/run-receipt

## Install

```bash
npx candor-ui add run-receipt
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/run-receipt`.
It brings in: locale, ops, relative-time, scale, status-dot, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { RunReceipt } from "@/components/run-receipt"
import type { RunReceipt as RunReceiptData } from "@/lib/ops"

const receipt: RunReceiptData = {
  runId: "run_7f3a91",
  title: "Add region to projects",
  startedAt: new Date(Date.now() - 48 * 60_000).toISOString(),
  duration: 431,
  status: "succeeded",
  models: [
    { model: "Claude Opus 5.5", inputTokens: 182_400, outputTokens: 9_820, cachedTokens: 141_000, cost: 1.94 },
    { model: "Claude Haiku 5.5", inputTokens: 22_100, outputTokens: 1_900, cost: 0.02 },
    { model: "Self-hosted embedder", inputTokens: 48_000, outputTokens: 0 },
  ],
  toolCalls: 38,
  meters: [{ label: "Database queries", value: "1,204" }, { label: "Staging compute", value: "6 min" }, { label: "GitHub API calls" }],
  costNote: "The self-hosted embedder doesn’t report cost.",
}

export default function Example() {
  return <RunReceipt className="max-w-2xl" receipt={receipt} />
}
```

## <RunReceipt>

Props:

- `receipt: RunReceiptData`: The run's measured usage. A model without a cost counts as not measured.
- `className?: string | undefined`

## Strings (`runReceipt`)

The fixed words, English by default. Override any of them under `runReceipt` in `<LocaleProvider strings={{ runReceipt: { … } }}>`; the table is exported as `runReceiptStrings`.

- `receiptFor`: Receipt for {title}
- `costNotMeasured`: Cost not measured
- `partialSoFar`: partial, so far
- `partialNotMeasured`: partial: some costs not measured
- `soFar`: so far
- `total`: total
- `model`: Model
- `in`: In
- `out`: Out
- `cached`: Cached
- `cost`: Cost
- `noModelUsage`: No model usage recorded.
- `notMeasured`: Not measured
- `toolCalls`: Tool calls

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.