Tracing and analytics
Trace reference: spans and attributes
Every span a chat request records, what each one means, and the attributes you can filter and read.
Reference2 min readUpdated 23 October 2026
Traces are OpenTelemetry spans. Attribute names follow the OpenTelemetry gen_ai.* semantic conventions where they exist. A chat request records these spans; not every request has every span.
Spans
| Span | What it covers |
|---|---|
chat.request | The whole request: agent, model, status and duration. The root of the trace |
auth.validate_user | Checking the key |
agent.fetch | Loading the agent's configuration (cached for a few minutes) |
preflight.rate_limit | The agent's requests-per-minute check |
preflight.credits | Reserving the reply's credit |
mcp.discovery | Loading the agent's MCP servers and tools |
conversation.start_or_load | Creating a conversation or loading its history |
rag.prefetch | Hybrid search and rerank over the agent's knowledge |
agentic.round[n] | One round of the model deciding, calling tools and answering |
llm.chat | The call to the model provider, with tokens and time to first token |
tool.execute | One tool call, with its outcome and timing |
synthesis.forced | The final answer forced after the tool rounds ran out or a call repeated |
There is no separate rerank span: reranking happens inside rag.prefetch and shows as its rag.reranked attribute.
Useful attributes
| Attribute | Meaning |
|---|---|
gen_ai.usage.input_tokens, output_tokens, total_tokens | Tokens for the request |
| model, provider | The model and provider used |
| temperature, max tokens | The settings the model was called with |
| time to first token | How long until the first delta, the latency users feel |
request.duration_ms | End-to-end duration |
request.cost_usd | Estimated model cost; only meaningful when token prices are set (see below) |
answer.cached | The answer came from the 15-minute answer cache |
rag.* | Retrieval scores, whether results were reranked, and how many sources were used |
gen_ai.tool.name, tool.success, tool.source | Per tool call: which tool, whether it worked, and whether it was MCP, knowledge search or a skipped repeat |
error.code | The error code, matching the API's error event |
credits.balance | Your credit balance at the time |
Cost figures
Model cost is estimated from token prices you set; SentientOne doesn't know your provider's prices. Set input and output prices per million tokens in the agent's Settings to see estimates on its Cost tab. Your provider's bill is the source of truth.
Reading traces from the API
GET /v1/traces lists your recent chat.request root spans; filter with agent_id, from and to (ISO datetimes), status=ok|error, limit (1 to 500, default 50) and offset. GET /v1/traces/{trace_id} returns one trace. Both take your secret key in X-Api-Key.
curl "https://api.sentientone.ai/v1/traces?status=error&limit=20" \ -H "X-Api-Key: $SENTIENTONE_API_KEY"curl "https://api.sentientone.ai/v1/traces/$TRACE_ID" \ -H "X-Api-Key: $SENTIENTONE_API_KEY"Retention
Traces are kept for 90 days, then deleted automatically. Deleting your account removes your agents and conversations at once; traces already recorded expire on the same 90-day schedule.
Related
Still stuck?
Email us with what you tried and any request id. A person replies.