Event schema

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

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.

"llm" | "tool"

required

Event type discriminator.

string

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

string

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

number

required

Call start, milliseconds since the Unix epoch.

number

required

Call end, milliseconds since the Unix epoch.

number

required

Call duration in milliseconds, typically endTimeMs - startTimeMs.

object

required

Outcome of the call.

Show status fields

"ok" | "error"

required

Whether the call succeeded.

object

Failure details when state is "error".

Show error fields

string

Machine-readable code, for example rate_limit_exceeded.

number

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

string

Human-readable description.

object

required

Where the event came from.

Show instrumentation fields

"carbon"

required

Always "carbon".

"sdk"

Set by the Carbon SDK.

"openai" | "anthropic" | "vercel"

required

The instrumented SDK or framework.

"openai" | "@anthropic-ai/sdk" | "ai"

required

The instrumented package.

string

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

object

required

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

Show context fields

string

Conversation or session identifier.

string

Agent instance identifier.

string

Identifier for a group of related agents.

string

End-user identifier.

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:

string

required

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

string

The API base URL the request was served from, for example https://api.openai.com/v1. The ingest API resolves provider and cost from it; the SDK wrappers capture it automatically, so set it only for manual capture.

string

The platform that executed the request, for example openai or openrouter. Derived by the ingest API from the API base URL — omit it.

string

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

object

What was sent to the model.

Show input fields

string

required

System prompt. Empty string when none.

string

required

User prompt or serialized message history.

object[]

required

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

object

What the model returned.

Show output fields

"generate" | "stream"

required

How the response was produced.

string

Reasoning output, for models that expose it.

string

Text response.

object[]

required

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

object

required

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

Show usage fields

number

required

Total input tokens.

object

required

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

number

required

Total output tokens.

object

required

{ reasoningTokens, responseTokens } — output token breakdown.

number

required

Input plus output tokens.

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:

string

required

Tool name, for example get_weather.

string

Serialized tool input, typically JSON.

string

Serialized tool output, typically JSON.

Example events

{
  "type": "llm",
  "id": "7d9f2a4e-3c1b-4f6a-9e8d-2b5c7a1f4e3d",
  "traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
  "startTimeMs": 1781176800000,
  "endTimeMs": 1781176801200,
  "durationMs": 1200,
  "status": { "state": "ok" },
  "instrumentation": {
    "vendor": "carbon",
    "source": "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
      }
    }
  }
}

{
  "type": "tool",
  "id": "9c2e7b1f-5a4d-4c8e-b3f6-1d9a2e7c4b5f",
  "traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
  "startTimeMs": 1781176801300,
  "endTimeMs": 1781176801650,
  "durationMs": 350,
  "status": { "state": "ok" },
  "instrumentation": {
    "vendor": "carbon",
    "source": "vercel",
    "sourcePackage": "ai"
  },
  "context": { "userId": "user-481", "agentId": "travel-agent" },
  "additionalProperties": {},
  "properties": {
    "tool": {
      "name": "get_weather",
      "input": "{\"city\":\"Tokyo\"}",
      "output": "{\"city\":\"Tokyo\",\"tempC\":22}"
    }
  }
}

Overview

Endpoints

Schemas

Common fields

LLM events

Tool events

Example events

​Common fields

​LLM events

​Tool events

​Example events

Common fields

LLM events

Tool events

Example events