Reference

Data model

Span kinds

staso.SpanKind:

Value	Use
`llm`	LLM call. Set by `patch_openai` / `patch_anthropic`.
`tool`	Tool function. Set by `@st.tool`.
`chain`	Generic. Default for `st.span` and `@st.trace`.
`retriever`	Vector search, SQL, document lookup.
`agent`	Agent entry-point. Set by `@st.agent`. Usually the root span.
`custom`	Anything else.

Statuses

staso.SpanStatus:

Value	When
`ok`	Default. Operation succeeded.
`error`	Set by `record_exception` or any decorator that catches an exception.
`timeout`	Manual via `span.set_status(SpanStatus.TIMEOUT)`.

Span shape

Field	Type	Description
`name`	`str`	Span label.
`kind`	`SpanKind`	See above.
`status`	`SpanStatus`	See above.
`trace_id`	`uuid`	Shared across every span in one trace.
`span_id`	`uuid`	Unique per span.
`parent_span_id`	`uuid \| null`	`null` for root.
`model`	`str`	LLM model name. Populated on `kind=llm`.
`input_tokens`	`int`
`output_tokens`	`int`
`total_tokens`	`int`
`input`	`dict`	Free-form request payload.
`output`	`dict`	Free-form response payload.
`metadata`	`dict`	Well-known keys (below) plus your own.
`conversation_id`	`str`	Set by `st.conversation` or context.
`agent_name`	`str`	Set by `@st.agent` or `st.init`.
`agent_id`	`str`	Deterministic UUID5 of `agent_name`.
`user_id`	`str`	Set by `st.conversation(user_id=...)`.
`error_message`	`str \| null`	Set by `record_exception`.

Well-known metadata keys

Use these exact strings so the backend can index and chart them.

LLM request

Key	Type
`temperature`	`float`
`max_tokens`	`int`
`top_p`	`float`
`top_k`	`int`
`stop_sequences`	`list[str]`
`tool_choice`	`str \| dict`
`thinking`	`dict`
`service_tier`	`str`
`response_format`	`str \| dict`
`frequency_penalty`	`float`
`presence_penalty`	`float`
`seed`	`int`

LLM response

Key	Type
`stop_reason`	`str`
`stop_sequence`	`str`
`response_id`	`str`
`provider`	`str`

Tokens

Key	Type
`cache_read_input_tokens`	`int`
`cache_creation_input_tokens`	`int`
`reasoning_tokens`	`int`
`audio_input_tokens`	`int`
`audio_output_tokens`	`int`

Performance

Key	Type
`time_to_first_token`	`float` seconds

Code location (set by decorators)

Key	Type
`code.filepath`	`str`
`code.lineno`	`int`
`code.function`	`str`

VCS (set by `capture_git=True`)

Key	Type
`vcs.commit.sha`	`str`
`vcs.branch`	`str`
`vcs.repo_url`	`str`
`vcs.is_dirty`	`bool`

Guard

Key	Type
`guard_action`	`str` — `allow \| block \| modify \| escalate`
`guard_reason`	`str`
`guard_latency_ms`	`float`

HTTP API

POST trace data directly from any language. Same schema, same auth, same rate limits as the SDK.

Environment variables

Every STASO_* env var the SDK reads.

On this page

Data model Span kinds Statuses Span shape Well-known metadata keys LLM request LLM response Tokens Performance Code location (set by decorators)VCS (set by capture_git=True)Guard Related