Observability

Every session carries its own running cost and token usage on the object itself, emits a usage snapshot before it yields control, and records a full turn/tool/model span tree you can read back from the event history.

Cost and usage on the session

Every session exposes what it has spent and consumed so far, without a separate billing call. Money is always integer micro-USD on the wire (1 USD = 1,000,000 micro-USD); clients convert for display.

vetta session get $SID    # includes consumed_micro_usd + token_usage

const s = await vetta.sessions.get(sessionId);
console.log(s.consumed_micro_usd);  // e.g. 410000  → $0.41
console.log(s.token_usage);         // 5-tier breakdown, below

Token usage is metered in five tiers, billed and reported separately, because they price very differently:

Tier	What it counts
`input`	Fresh prompt tokens sent to the model.
`cache_write`	Tokens written into the prompt cache.
`cache_read`	Tokens served from the prompt cache (cheapest).
`output`	Tokens the model generated.
`reasoning`	Hidden reasoning/thinking tokens, when the model produces them.

The session object carries consumed_micro_usd, token_usage (the five tiers above), started_at, ended_at?, stop_reason?, deployment_id?, agent_version, and last_seq — enough to attribute cost per run, per deployment, and per agent version.

The `session.usage` event

Before a session transitions to idle or any terminal state, the runtime emits a session.usage event carrying the cumulative snapshot. Because it precedes every yield, a stream consumer always sees the final cost of a turn before it sees the turn end.

{
  "id": "evt_5c...",
  "type": "session.usage",
  "seq": 142,
  "data": {
    "session_id": "ses_4a...",
    "consumed_micro_usd": 410000,
    "token_usage": {
      "input": 18240,
      "cache_write": 4096,
      "cache_read": 51200,
      "output": 3110,
      "reasoning": 900
    },
    "active_seconds": 37,
    "tool_calls": 12
  }
}

active_seconds is metered running time — paused/idle time is excluded, matching how the computer bills.
tool_calls is the count of tool invocations in the run so far.
The event rides the ordinary seq cursor, so it is replayable like any other event.

Reading session.usage on the idle event pairs naturally with outcomes: report cost per completed and passing task, not just cost per attempt.

The span model

Every session records a full trace of its turns, tool calls, and model requests — read it with vetta session events --session $SID. The spans follow the OpenTelemetry GenAI semantic conventions, so they line up with any tooling that already understands agent traces:

Vetta concept	OTel span / attribute
Session	trace, with `gen_ai.conversation.id` = the session id
Agent	`gen_ai.agent.id` and `gen_ai.agent.version` on the spans
Each turn	an `invoke_agent` span
Each tool call	an `execute_tool` span (child of the turn)
Each model call	a `chat` span carrying the five token tiers + cost

A single turn therefore nests as invoke_agent → (chat, execute_tool, execute_tool, …), so you can see exactly which tool call or model request drove a turn’s latency and cost. Coming soon: OTLP export of these spans to an OpenTelemetry-compatible collector you control.

Next: deployments

Run an agent on a schedule and collect every fire’s cost and result.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Observability

Cost and usage on the session

The `session.usage` event

The span model

Next: deployments

​Cost and usage on the session

​The session.usage event

​The span model

Next: deployments

Cost and usage on the session

The `session.usage` event

The span model