Traces

Open a session's Trace tab in the console to see its turns, model requests, tool calls, and compaction. Use the timeline to find slow requests or failed tools, then inspect their inputs, results, and reported usage.

You can also read traces through the API with read scope:

const trace = await client.traces.forSession({
  id: sessionId,
  includeDescendants: true
})

for (const span of trace.spans) {
  console.log(span.name, span.kind, span.status, span.attributes)
}

Each span includes its ID, parent ID, start and end times, status, attributes, and events. kind is turn, model, tool, or compaction. Model attributes help identify the provider request, model, cache prefix, and fallback attempt.

includeDescendants: true includes sub-agent spans so you can inspect delegated work alongside its parent. Each child also has its own session trace.

Cost and caching

Model usage and cache counters appear beside requests when reported by the provider. See usage for totals and spend caps, and context and caching to diagnose changes in cache reuse.

Retention

The environment's spansDays setting controls trace retention. When spans have been pruned, the response includes prunedAt. See retention for defaults and how to configure them.

Traces can contain customer data, including tool inputs and results. Limit access to the people and services that need to inspect it.