Skip to main content
A session groups multiple runs into a single conversation between a user and your agent. Sessions are how you analyze multi-turn behavior instead of single-shot completions.

​
How sessions are formed

Set tcc.sessionId on every run in a conversation. The value can be any stable string (a UUID is recommended when your product doesn’t already have a conversation identifier).
Sessions are automatically indexed and become a first-class filter on the dashboard, REST API, and MCP.

​
What you can analyze at the session level

  • Full conversation view. See every run in order, the user’s messages, the agent’s responses, and the tool calls that ran between them.
  • Multi-turn failure patterns. Find sessions where the user repeated the same question, gave up, or expressed frustration only later in the conversation.
  • Time-to-resolution. How many runs a typical resolution takes, and where sessions get stuck.
  • Session-level feedback. Feedback attached to any run inside the session surfaces at the session level too.
  • Per-session cost and latency. Cost and duration aggregated across every run in the session.
Example Insight Search queries:
Show me sessions with more than 5 back-and-forth messages where the user eventually gave up. What was the agent getting stuck on?
Which sessions had the highest cost this week, and what were users asking about?

​
Sessions in the API

Filter by agent, userId, or orgId. See the API reference. The MCP get_agent_sessions tool exposes the same data to coding agents, with the option to fetch a conversation view (prompts and responses only) or a full_trace view (steps and tool calls included). See MCP.

​
Sessions and conversational runs

Only conversational runs (tcc.conversational: true) are analyzed for behavioral patterns like frustration and confusion. If a session mixes conversational turns with background executions, only the conversational runs contribute to behavioral analysis. Background runs still appear in the session view and in trace-level analyses.

Users and organizations

Sessions rolled up per end user and account.

Traces

Inside every session run.

Patterns

Behavioral signals detected across a session’s runs.

Feedback

Per-run feedback aggregated at the session level.