---
title: "Cost and token metrics"
description: "Cost, tokens, tool calls, success and latency per agent, project, team, pull request and task, and the reconciliation with metered usage."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost and token metrics

A metric is a number with a kind, a time and dimensions. The kinds are `cost_micros`, `tokens`, `tool_calls`, `success`, `failure` and `latency_ms`. The dimensions are agent, project, team, pull request and task. Cost is in micro-dollars, whole numbers.

```sh
overlane observe cost
overlane observe reconcile
```

## Where metrics come from

- **Run events.** An event with a cost or token count adds those; a `run.step` with a tool adds a tool call; `run.ended` adds a success or a failure and the run's duration. A run names its task and pull request once and its later events inherit them.
- **Reported metrics.** An agent or the inference port can post metrics directly, up to 200 a call.

Every metric has an ID, and a metric ID counts once. A replayed event, a retried call and a metric sent twice change no total. A run's cost and tokens are recomputed from its metrics, never incremented.

## Reconciled with metered usage

The billing ledger meters hosted inference by the call, per agent and project. `overlane observe reconcile` compares that with the cost the metrics report, per agent, per project and in total, over the same window: this billing period, but no earlier than the plan's retention keeps. The tolerance is 1 percent (100 basis points); a line outside it is named with its error.

```js run
// Error is relative to the metered figure, in basis points, rounded up.
assert.equal(errorBps(100000, 100999), 100);
assert.equal(errorBps(100000, 101001), 101);
const lines = reconcileMaps(new Map([["codex", 1000]]), new Map([["codex", 1005], ["gemini", 10]]));
assert.equal(JSON.stringify(lines.map((line) => [line.key, line.within])), '[["codex",true],["gemini",false]]');
```

## Reading them

`overlane observe cost` groups cost, tokens and runs by agent, by project and for the team. The web cost table reads the same numbers in cents.

Command reference: [observe cost](/cli/observe-cost/) and [observe reconcile](/cli/observe-reconcile/). To stop a run at a limit, see [Budgets](/control-plane/budgets/).

Source: https://docs.overlane.app/observability/metrics/index.mdx