usage

Tokens and cost for a step, a run or a lane. Cost rolls up the trail and is always an estimate.

Direction: Harness → Chips
Sent by: a harness
Requires a run: yes
Schema: usage.json

Fields

Every event also carries the envelope.

Field	Required	Type	Description
v	yes	1	Protocol major version.
type	yes	"usage"
id	yes	string	The event’s own id. Stable across a retry of the same event.
ts	yes	string	When it happened, by Chips’ clock. Stamped on the way in; a value the sender writes is replaced.
workspace_id	yes	string	A workspace identifier: ws_ followed by a ULID.
space_id	no	string	The space, when the event belongs to one.
run_id	no	string	The run, when the event belongs to one.
seq	no	number	Assigned by the server on append, monotonic per workspace. Absent on the way in.
idempotency_key	no	string	Required on every client-originated write. Sending the same key twice is a no-op.
actor	yes	object	The participant an event is attributed to.
actor.kind	yes	"person" | "harness" | "agent" | "system"	Whether a person, a harness, one of a harness’s agents or Chips itself acted.
actor.id	yes	string	The participant id, or system for Chips.
actor.harness_id	no	string	For an agent: the harness it speaks through, whose budget and runs are the agent’s (ADR 0087). Filled in by Chips.
scope	yes	"step" | "run" | "lane"	What the numbers cover.
model	yes	string	The model that did the work.
input_tokens	no	number	Tokens in: every token the model read, fresh, read from its prompt cache and written to it. Leave it out when the harness cannot say: the tokens out are still counted, and Chips puts no price on a report it cannot count whole.
cache_read_tokens	no	number	Of the tokens in, how many the model read from its prompt cache. Leave it out when the harness cannot say or the model keeps no cache.
cache_write_tokens	no	number	Of the tokens in, how many the model wrote to its prompt cache. Leave it out when the harness cannot say or the model keeps no cache.
output_tokens	no	number	Tokens out. Leave it out when the harness cannot say, and send the cost: Chips prices only a report whose tokens it has whole.
cost	no	object	The estimated cost, when the harness can compute one.
cost.usd	yes	number	An estimate, in US dollars.
cost.estimated	yes	true	Always true. Cost is never presented as exact.

Example

{
  "v": 1,
  "type": "usage",
  "id": "evt_01K4ZQPX00000000000000006E",
  "ts": "2026-09-02T14:22:10.004Z",
  "workspace_id": "ws_01K4ZQPX000000000000000001",
  "space_id": "spc_01K4ZQPX000000000000000002",
  "actor": {
    "kind": "harness",
    "id": "hrn_01K4ZQPX000000000000000004"
  },
  "run_id": "run_01K4ZQPX000000000000000005",
  "scope": "run",
  "model": "opus-5",
  "input_tokens": 82140,
  "output_tokens": 3402,
  "cost": {
    "usd": 1.47,
    "estimated": true
  }
}