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 Client-generated UUIDv4 identifying the event. Unique within your space —
the deduplication key. Generate it once per event and reuse it across
retries.
Event type discriminator.
Set by the ingest API from your API key. Any client-supplied value is
overridden — omit it.
Call start, milliseconds since the Unix epoch.
Call end, milliseconds since the Unix epoch.
Call duration in milliseconds, typically endTimeMs - startTimeMs.
Outcome of the call. Whether the call succeeded.
Failure details when state is "error". Machine-readable code, for example rate_limit_exceeded.
HTTP status returned by the upstream provider, for example 429.
Human-readable description.
Where the event came from. Show instrumentation fields
sourceProvider
"openai" | "anthropic" | "vercel"
required
The instrumented provider or framework.
sourcePackage
"openai" | "@anthropic-ai/sdk" | "ai"
required
The instrumented package.
The wrapped function, for example chat.completions.create.
Identifiers the dashboard aggregates by. The object is required but every
field is optional — send {} when none apply. Conversation or session identifier.
Agent instance identifier.
Identifier for a group of related agents.
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:
Model identifier as the provider names it, for example gpt-5.4-nano or
claude-haiku-4-5.
Model provider, for example openai. Derived by the ingest API from the
model name when recognized — omit it.
Gateway the call went through when not calling the provider directly, for
example a model router.
What was sent to the model. System prompt. Empty string when none.
User prompt or serialized message history.
Tools offered to the model: { name: string, description?: string }.
Empty array when none.
What the model returned. mode
"generate" | "stream"
required
How the response was produced.
Reasoning output, for models that expose it.
Tool calls the model requested: { name: string, input?: string } with
input as the serialized arguments. Empty array when none.
Token usage. All fields are required — use 0 where a provider does not
report a breakdown. { uncachedTokens, cacheReadTokens, cacheWriteTokens } — input token
breakdown by cache behavior.
{ reasoningTokens, responseTokens } — output token breakdown.
Input plus output tokens.
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 set type: "tool" and carry properties.tool:
Tool name, for example get_weather.
Serialized tool input, typically JSON.
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" : { "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 } } } }
