Event schema

The canonical event contract, field by field: common fields, LLM events, and tool events.

Events are a discriminated union on type: "llm" or "tool". Both share the common fields below and add a type-specific properties object. The SDK validates events against this contract before sending; the ingest API validates again on receipt.

Common fields

id · string · required

Client-generated UUIDv4 identifying the event. Unique within your space — the deduplication key. Generate it once per event and reuse it across retries.

type · "llm" | "tool" · required

Event type discriminator.

spaceId · string

Set by the ingest API from your API key. Any client-supplied value is overridden — omit it.

traceId · string

UUIDv4 shared by the events of one logical operation. See Traces and context.

startTimeMs · number · required

Call start, milliseconds since the Unix epoch.

endTimeMs · number · required

Call end, milliseconds since the Unix epoch.

durationMs · number · required

Call duration in milliseconds, typically endTimeMs - startTimeMs.

status · object · required

Outcome of the call.

Show status fields

state · "ok" | "error" · required

Whether the call succeeded.

error · object

Failure details when state is "error".

Show error fields

code · string

Machine-readable code, for example rate_limit_exceeded.

httpStatus · number

HTTP status returned by the upstream provider, for example 429.

message · string

Human-readable description.

instrumentation · object · required

Where the event came from.

Show instrumentation fields

provider · "carbon" · required

Always "carbon".

providerPackage · "sdk"

Set by the Carbon SDK.

sourceProvider · "openai" | "anthropic" | "vercel" · required

The instrumented provider or framework.

sourcePackage · "openai" | "@anthropic-ai/sdk" | "ai" · required

The instrumented package.

sourceFunction · string

The wrapped function, for example chat.completions.create.

context · object · required

Identifiers the dashboard aggregates by. The object is required but every field is optional — send {} when none apply.

Show context fields

threadId · string

Conversation or session identifier.

agentId · string

Agent instance identifier.

agentGroupId · string

Identifier for a group of related agents.

userId · string

End-user identifier.

additionalProperties · Record<string, string | number> · required

Custom dimensions. Values must be strings or numbers — send {} when none apply.

LLM events

LLM events set type: "llm" and carry properties.llm:

properties.llm.model · string · required

Model identifier as the provider names it, for example gpt-5.4-nano or claude-haiku-4-5.

properties.llm.provider · string

Model provider, for example openai. Derived by the ingest API from the model name when recognized — omit it.

properties.llm.gateway · string

Gateway the call went through when not calling the provider directly, for example a model router.

properties.llm.input · object

What was sent to the model.

Show input fields

system · string · required

System prompt. Empty string when none.

prompt · string · required

User prompt or serialized message history.

tools · object[] · required

Tools offered to the model: { name: string, description?: string }. Empty array when none.

properties.llm.output · object

What the model returned.

Show output fields

mode · "generate" | "stream" · required

How the response was produced.

reasoning · string

Reasoning output, for models that expose it.

response · string

Text response.

toolCalls · object[] · required

Tool calls the model requested: { name: string, input?: string } with input as the serialized arguments. Empty array when none.

properties.llm.usage · object · required

Token usage. All fields are required — use 0 where a provider does not report a breakdown.

Show usage fields

inputTokens · number · required

Total input tokens.

inputTokenDetails · object · required

{ uncachedTokens, cacheReadTokens, cacheWriteTokens } — input token breakdown by cache behavior.

outputTokens · number · required

Total output tokens.

outputTokenDetails · object · required

{ reasoningTokens, responseTokens } — output token breakdown.

totalTokens · number · required

Input plus output tokens.

properties.llm.cost · object

USD cost breakdown: { inputUncachedUsd, inputCacheReadUsd, inputCacheWriteUsd, outputUsd, totalUsd }. Computed by the ingest API from its model catalog when the model is recognized — omit it.

Tool events

Tool events set type: "tool" and carry properties.tool:

properties.tool.name · string · required

Tool name, for example get_weather.

properties.tool.input · string

Serialized tool input, typically JSON.

properties.tool.output · string

Serialized tool output, typically JSON.

Example events

LLM event

{
  "type": "llm",
  "id": "7d9f2a4e-3c1b-4f6a-9e8d-2b5c7a1f4e3d",
  "traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
  "startTimeMs": 1781176800000,
  "endTimeMs": 1781176801200,
  "durationMs": 1200,
  "status": { "state": "ok" },
  "instrumentation": {
    "provider": "carbon",
    "sourceProvider": "anthropic",
    "sourcePackage": "@anthropic-ai/sdk",
    "sourceFunction": "messages.create"
  },
  "context": { "userId": "user-481", "threadId": "thread-92" },
  "additionalProperties": { "release": "2026-06" },
  "properties": {
    "llm": {
      "model": "claude-haiku-4-5",
      "input": {
        "system": "You are concise.",
        "prompt": "What is the capital of France?",
        "tools": []
      },
      "output": {
        "mode": "generate",
        "response": "Paris.",
        "toolCalls": []
      },
      "usage": {
        "inputTokens": 18,
        "inputTokenDetails": {
          "uncachedTokens": 18,
          "cacheReadTokens": 0,
          "cacheWriteTokens": 0
        },
        "outputTokens": 3,
        "outputTokenDetails": { "reasoningTokens": 0, "responseTokens": 3 },
        "totalTokens": 21
      }
    }
  }
}