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

PartContents
IdentityA client-generated UUID id and an optional traceId grouping related events
TimingstartTimeMs, endTimeMs, and durationMs
Statusok or error, with optional error code, HTTP status, and message
InstrumentationWhich wrapper and source SDK produced the event
ContextOptional userId, agentId, agentGroupId, and threadId identifiers
Custom dimensionsadditionalProperties — your own string and number key-values
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 and context.

​
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 provider is derived from the model name using Carbon’s model catalog.
  • Cost — when the model is in the catalog, 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.