Skip to main content
Context is what makes the ledger queryable. Every event carries the same optional metadata object, and its context fields are the identifiers the dashboard aggregates by — the dimensions you tag are exactly the ones you can later slice cost and usage by. 
type CarbonMetadata = {
  traceId?: string;
  context?: {
    threadId?: string;
    agentId?: string;
    agentGroupId?: string;
    userId?: string;
  };
  additionalProperties?: Record<string, string | number>;
};
The shape is identical whether an event comes from an SDK wrapper, a wrapped tool, or manual capture.

​
Context fields

Context fields are the built-in dimensions. All are optional strings whose meaning is defined by your application:
FieldWhat it identifiesPowers
userIdThe end user behind the callUsers analytics
agentIdThe agent instance or roleAgents analytics
agentGroupIdA group of related agentsAgent group filters
threadIdA conversation or sessionThreads analytics
carbon: {
  context: {
    userId: "user-481",
    agentId: "support-agent",
    threadId: "thread-92",
  },
}
Set the fields that match your product’s shape — a chat product benefits from threadId and userId; a multi-agent system from agentId and agentGroupId. Events tagged with these light up the dimension pages in the dashboard; events without them still record, but cannot be sliced by that dimension.

​
Custom properties

additionalProperties holds your own dimensions as string or number values — release tags, environment names, experiment arms: 
carbon: {
  additionalProperties: {
    release: "2026-06",
    experiment: "prompt-v2",
    region: "eu-west-1",
  },
}

​
Where metadata goes

The same metadata object — traceId, context, and additionalProperties — attaches the same way from every capture path:
Pass a carbon field in the call arguments. The wrapper strips it before the request reaches the provider.
await openai.chat.completions.create({
  model: "gpt-5.4-nano",
  messages,
  carbon: { traceId, context: { userId: "user-481" } },
});
To correlate the events of one logical operation — an agent run, a request, a job — give them a shared traceId. See Traces.