> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncarbon.site/llms.txt
> Use this file to discover all available pages before exploring further.

# The event model

> Events are the unit of Carbon's ledger: what they contain, the two event types, and what Carbon enriches on ingest.

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

<Columns cols={2}>
  <Card title="LLM events" icon="message-square">
    One model invocation: model identity, prompts, output, token usage, and
    cost in USD.
  </Card>

  <Card title="Tool events" icon="wrench">
    One tool execution: tool name plus serialized input and output.
  </Card>
</Columns>

Both types share a common base, so they can be filtered, traced, and aggregated together.

## What every event carries

| Part              | Contents                                                                       |
| ----------------- | ------------------------------------------------------------------------------ |
| Identity          | A client-generated UUID `id` and an optional `traceId` grouping related events |
| Timing            | `startTimeMs`, `endTimeMs`, and `durationMs`                                   |
| Status            | `ok` or `error`, with optional error code, HTTP status, and message            |
| Instrumentation   | Which wrapper and source SDK produced the event                                |
| Context           | Optional `userId`, `agentId`, `agentGroupId`, and `threadId` identifiers       |
| Custom dimensions | `additionalProperties` — your own string and number key-values                 |

The complete field-by-field contract is in the [event schema reference](/api-reference/schemas/event-schema).

## 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](/documentation/sdk/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.