> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontextcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations and sessions

> How The Context Company groups multi-turn conversations into sessions, and the analyses that unlocks.

A **session** groups multiple [runs](/concepts#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).

```ts theme={null}
metadata: {
  "tcc.runId": crypto.randomUUID(),
  "tcc.sessionId": conversation.id,
  "tcc.conversational": true,
}
```

Sessions are automatically indexed and become a first-class filter on the dashboard, [REST API](/access-data/api#sessions), and [MCP](/access-data/mcp#get_agent_sessions).

## 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

```bash theme={null}
GET /v1/sessions?range=2w&limit=10
GET /v1/sessions/:sessionId
```

Filter by `agent`, `userId`, or `orgId`. See the [API reference](/access-data/api#sessions).

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](/access-data/mcp#get_agent_sessions).

## Sessions and conversational runs

Only [conversational runs](/concepts#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.

## Related

<CardGroup cols={2}>
  <Card title="Users and organizations" icon="users-viewfinder" href="/analyze/users-and-organizations">
    Sessions rolled up per end user and account.
  </Card>

  <Card title="Traces" icon="diagram-project" href="/investigate/traces">
    Inside every session run.
  </Card>

  <Card title="Patterns" icon="magnifying-glass" href="/analyze/patterns">
    Behavioral signals detected across a session's runs.
  </Card>

  <Card title="Feedback" icon="thumbs-up" href="/analyze/feedback">
    Per-run feedback aggregated at the session level.
  </Card>
</CardGroup>