Skip to main content
Everything in Carbon is built on one canonical record: the event. An event describes a single LLM call or a single tool execution. The dashboard’s analytics — cost, usage, latency, errors, and every breakdown by agent, model, user, and thread — are aggregations over events.

​
Two event types

LLM events

One model invocation: model identity, prompts, output, token usage, and cost in USD.

Tool events

One tool execution: tool name plus serialized input and output.
Both types share a common base, so they can be filtered, traced, and aggregated together.

​
What every event carries

The complete field-by-field contract is in the event schema reference.

​
Traces

A trace is a set of events sharing a traceId — the steps of one agent run, one request, one job. Carbon never infers grouping; you pass the trace ID explicitly (or a wrapper propagates it through a multi-step call). See Traces.

​
What Carbon adds on ingest

The ingest API enriches events as they arrive:
  • Space — the spaceId is always set from the authenticated API key. Anything the client sends is overridden.
  • Provider — for LLM events, the platform that ran the call (the model’s own API, or a gateway like Vercel/OpenRouter) is resolved from the captured request base URL.
  • Creator — the model’s maker (e.g. anthropic, google) is resolved from the model id.
  • Cost — when the provider lists the model, USD cost is computed from token usage and current pricing, broken down by uncached input, cache reads, cache writes, and output.
Client-supplied values for these fields are not trusted; everything else on the event is yours.

​
Payloads

When available, events carry full call payloads — system prompt, user prompt, model response, reasoning, and serialized tool input and output. Carbon archives the complete event durably and keeps the analytics store lean, so aggregate queries stay fast while the exact call remains inspectable.