# RunMeter

> Tokens, estimated cost from your rates, time to first token and the prompt-cache hit rate.

Source: https://agent-ui-kit-demo.vercel.app/docs/components/run-meter

## Installation

From npm:

```bash
npm i @dgesteves/agent-ui-kit ai
```

```tsx
import { RunMeter, useRunTiming } from '@dgesteves/agent-ui-kit';
import '@dgesteves/agent-ui-kit/styles.css'; // once per app, or @import '@dgesteves/agent-ui-kit/tailwind.css' with Tailwind v4
```

Or as source, with the shadcn CLI:

```bash
npx shadcn@latest add @agent-ui-kit/run-meter
```

```tsx
import { RunMeter } from '@/components/agent-ui/run-meter';
import { useRunTiming } from '@/components/agent-ui/lib/hooks';
```

## Usage

```tsx
const timing = useRunTiming(status);

<RunMeter
  variant="expanded"
  usage={last?.metadata?.usage}
  pricing={{ input: 2.5, cachedInput: 0.25, output: 10 }} // USD per million tokens
  ttftMs={timing.ttftMs}
  durationMs={timing.activeMs}
  live={status === 'streaming'}
/>
```

## API reference

### RunMeter

Token usage, estimated cost and latency for an agent run.
`compact` is a single inline strip for headers; `expanded` is a card with a
token breakdown bar and the prompt-cache hit rate.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `RunUsage` |  |  |
| `pricing` | `ModelPricing` |  | Used to estimate cost when `cost` is not given. |
| `cost` | `number` |  | Explicit cost in USD, e.g. reported by your gateway. |
| `ttftMs` | `number` |  | Time to first token, ms. |
| `durationMs` | `number` |  | Total (active) run time, ms. |
| `live` | `boolean` | `false` | The run is in progress: values are live. |
| `model` | `string` |  |  |
| `variant` | `'compact' \| 'expanded'` | `'compact'` |  |
| `title` | `ReactNode` | `'Run'` | Heading for the expanded variant. |
| `headingLevel` | `HeadingLevel` | `3` | Heading level for the expanded variant's title. |

Other props go to the root `<div>`: `className`, `id`, `aria-*`, `data-*` and event handlers.

### ModelPricing

USD per million tokens.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` (required) | `number` |  |  |
| `output` (required) | `number` |  |  |
| `cachedInput` | `number` |  | Price for cache-read input tokens. Defaults to `input`. |
| `cacheWrite` | `number` |  | Price for input tokens written to the prompt cache (e.g. 1.25x input on Anthropic). Defaults to `input`. |

### RunUsage

Token usage, compatible with the AI SDK `LanguageModelUsage` shape.

```ts
type RunUsage = {
  inputTokens?: number | undefined;
  outputTokens?: number | undefined;
  totalTokens?: number | undefined;
  inputTokenDetails?: Partial<LanguageModelUsage['inputTokenDetails']> | undefined;
  outputTokenDetails?: Partial<LanguageModelUsage['outputTokenDetails']> | undefined;
};
```

## Accessibility

- The compact strip is a group named "Run metrics" with one visually hidden sentence, such as "20.9k input tokens, 255 output tokens, estimated cost $0.025, …", instead of a run of loose numbers.
- The expanded card has a heading (`title`, at `headingLevel`) and a labelled token breakdown list.
- Numbers tween as they change, except with `prefers-reduced-motion`.

## Theming

Slots (`data-slot`): `run-meter`.

- `data-variant` on `run-meter`: 'compact' | 'expanded'

Tokens it uses: `--aui-accent`, `--aui-accent-fg`, `--aui-border`, `--aui-chart-input`, `--aui-chart-output`, `--aui-fg`, `--aui-fg-muted`, `--aui-fg-subtle`, `--aui-font-mono`, `--aui-font-sans`, `--aui-radius`, `--aui-ring`, `--aui-surface`, `--aui-surface-2`. See https://agent-ui-kit-demo.vercel.app/docs/getting-started#theming.