# harn usage — LLM spend and usage analytics

> harn usage turns the per-call cost and token data Harn already records in the event log into spend and usage rollups by provider, model, stage, or a day/week/month time series....

Website: https://harnlang.com/usage.html

This page documents Harn, which is pre-1.0. Language, standard library, and CLI APIs may change. If the intended version is unclear, clarify before using this page.

---

# `harn usage` — LLM spend and usage analytics

`harn usage` turns the per-call cost and token data Harn **already records** in
the event log into spend and usage rollups by provider, model, stage, or a
day/week/month time series. It also reports prompt-cache efficiency.

Every LLM call the runtime makes appends a `provider_call_response` event to the
`agent.transcript.llm` topic in `<project>/.harn/events.sqlite`. That event
already carries `provider`, `model`, token counts, cache telemetry, known cost,
and whether the provider reported enough information to trust those numbers.
`harn usage` reads those events through the same
event-log reader `harn portal` uses, filters to `provider_call_response`
records, and aggregates them. It does **not** recompute pricing. Known cost and
unpriced/unknown counts are summed straight from the event.

## Quick start

```bash
# Default: by-provider table for the current project's event log, all-time.
harn usage

# A specific project.
harn usage --project ~/projects/my-service

# Roll up across every discoverable project event log.
harn usage --all
```

Example output:

```text
harn usage — 4329 provider calls in 4320 responses across 1 source, $18.8753 by provider

provider               calls  known cost      in_tok    out_tok   cache%  cache_save  ms/response
openrouter              2880    $16.5757    62298223    1096570    25.8%     $1.8904       3781
cerebras                 613     $2.2948     7622388     293140    41.0%     $0.0000        961
anthropic                  1     $0.0019          10        123     0.0%    $-0.0079       4710
llamacpp                 829     $0.0000    12640752     177160    40.6%     $0.0000      14967

total: 4329 provider calls, $18.8753, 82566555 in / 1567871 out tok, $1.8826 cache savings
```

## Options

| Flag | Description |
| --- | --- |
| `--project <path>` | Project root whose `.harn/events.sqlite` to read. Defaults to the current directory. Ignored when `--all` is set. |
| `--all` | Discover and aggregate across every `<project>/.harn/events.sqlite` found under the current directory and `~/projects`, skipping vendored `.cargo/registry` copies and any `node_modules` trees. |
| `--since <date>` | Only include calls at or after this date (inclusive). Accepts `YYYY-MM-DD` or an RFC3339 timestamp. |
| `--until <date>` | Only include calls strictly before this date. A bare `YYYY-MM-DD` is inclusive of the whole day. |
| `--group-by provider\|model\|stage\|day\|week\|month` | Roll-up dimension. Defaults to `provider`. Agent loops label their own work, checks, repairs, wrap-up, and compaction calls. Calls without a meaningful stage appear under `unattributed`. |
| `--provider <p>` | Only include rows for this provider. |
| `--model <m>` | Only include rows for this model. |
| `--json` | Emit the stable [`JsonEnvelope`](./cli-json-contract.md) instead of the text table. |
| `--csv` | Emit CSV rows instead of the text table. |

`mock`-provider rows are always excluded, so fixture and offline-demo calls
never contaminate real spend. There is no flag to include them.

## Metrics

Each group reports:

- `responses` — number of durable `provider_call_response` records
- `provider_calls` — number of physical provider requests represented by those
  records, including retries
- `cost_status` / `usage_status` — independent `no_calls`, `reported`,
  `partial`, or `unknown` completeness signals for price and token accounting;
  only `reported` makes that dimension's numeric zero a complete measurement
- `known_cost_usd` — measured cost only
- `unpriced_calls` / `usage_unknown_calls` — provider requests whose cost or
  token usage is absent
- `input_tokens` / `output_tokens`
- `cache_read_tokens` / `cache_write_tokens`
- `cache_savings_usd` — sum of the runtime's per-call cache-savings estimate
- `cache_hit_ratio` — response-weighted mean of the runtime's normalized
  prompt-cache ratio
- `mean_response_ms`
- `cumulative_known_cost_usd` — running measured-cost total, on the
  `day`/`week`/`month` series

## Time series

```bash
harn usage --group-by day --since 2026-06-01
```

Day/week/month group-bys are ordered chronologically and carry a
`cumulative_known_cost_usd` column so you can see measured spend accrue over
the window. Each row still exposes its unpriced-call count, so the cumulative
number cannot be mistaken for a complete bill when accounting is partial.

## JSON envelope

`--json` returns the same versioned envelope shape every `harn … --json`
command uses (`schemaVersion`, `ok`, `data`, `error`, `warnings`). The `data`
payload is a `UsageReport` with `group_by`, `sources`, `responses`,
`provider_calls`, `groups`, and `totals`. Agents can negotiate compatibility
via `harn --json-schemas`, which
lists `usage` and its schema version.

## Scope and limitations

- The event log is a **lower bound** on spend: it rotates, and it only records
  LLM calls made through Harn orchestration. Non-Harn spend is not captured.
- Reconciling against provider billing APIs / Langfuse (`--backfill`) is a
  planned follow-up. It is not implemented in v1 and errors if requested.

## Related

- [Harn portal](./portal.md) — the observability UI over the same event log.
- [CLI `--json` contract](./cli-json-contract.md).

---

## Read next

- [Harn portal](https://harnlang.com/portal.md)
- [Unified observability API](https://harnlang.com/observability/unified-api.md)