Traces & Spans

Detailed reference for the tracing data model.

Trace

A trace is the top-level container for a single agent execution.

Field	Type	Description
`id`	uuid	Unique trace identifier
`name`	string	Human-readable name
`status`	running \| success \| error	Current trace status
`input`	JSON	Input data passed to the agent
`output`	JSON	Final output from the agent
`tags`	string[]	Tags for filtering
`session_id`	string	Group traces by session
`duration_ms`	integer	Auto-calculated on endTrace
`metadata`	JSON	Arbitrary metadata

Span

A span represents a single step within a trace.

Field	Type	Description
`id`	uuid	Unique span identifier
`trace_id`	uuid	Parent trace
`parent_span_id`	uuid	Parent span (for nesting)
`name`	string	Human-readable name
`type`	llm \| tool \| retrieval \| agent \| chain \| span	Span type for color-coding
`model`	string	Model name (for LLM spans)
`provider`	string	Provider name (openai, anthropic, etc.)
`prompt_tokens`	integer	Input tokens used
`completion_tokens`	integer	Output tokens used
`total_tokens`	integer	Total tokens
`cost_usd`	number	Cost in USD
`duration_ms`	integer	Auto-calculated on endSpan
`error_message`	string	Error details if status is error

Span Types

Type	Color	When to use
`llm`	Blue	LLM API calls (OpenAI, Anthropic, etc.)
`tool`	Purple	Tool/function calls (database, API, etc.)
`retrieval`	Orange	RAG retrieval, vector search, knowledge base
`agent`	Green	Sub-agent execution
`chain`	Pink	Chain/pipeline steps
`span`	Gray	Generic step (default)

Nesting Spans

Pass parent_span_id when starting a span to create nested hierarchies:

⚡ The tree view in the dashboard automatically visualizes parent-child relationships between spans.

class=class="tk-str">"tk-cmt">// Nested spans example const traceId = await ai.startTrace({ name: class="tk-str">'rag-pipeline' }) const parentSpan = await ai.startSpan({ name: class="tk-str">'process-query', type: class="tk-str">'chain', }) class=class="tk-str">"tk-cmt">// Child span nested under parentSpan const retrieveSpan = await ai.startSpan({ name: class="tk-str">'vector-search', type: class="tk-str">'retrieval', parent_span_id: parentSpan, input: { query: class="tk-str">'product specs' }, }) await ai.endSpan(retrieveSpan, { output: { results: 5 }, status: class="tk-str">'success', }) class=class="tk-str">"tk-cmt">// Another child span const llmSpan = await ai.startSpan({ name: class="tk-str">'generate-answer', type: class="tk-str">'llm', parent_span_id: parentSpan, model: class="tk-str">'claude-3-5-sonnet', provider: class="tk-str">'anthropic', }) await ai.endSpan(llmSpan, { output: { answer: class="tk-str">'...' }, prompt_tokens: 1200, completion_tokens: 350, total_tokens: 1550, cost_usd: 0.0089, }) await ai.endSpan(parentSpan, { status: class="tk-str">'success' }) await ai.endTrace(traceId, { status: class="tk-str">'success' })