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.

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.

// 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 and observe reconcile. To stop a run at a limit, see Budgets.