---
title: "langsight sessions"
description: "List agent sessions and display multi-agent call trees"
---

## Usage

```bash
langsight sessions [OPTIONS]
```

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--config` | auto-discovered | Path to `.langsight.yaml` |
| `--window`, `-w` | `24h` | Look-back window (24h, 7d, 30d) |
| `--agent`, `-a` | all agents | Filter sessions by agent name |
| `--health-tag` | — | Filter by health tag (v0.3): `success`, `loop_detected`, `budget_exceeded`, `tool_failure`, `circuit_breaker_open`, `timeout`, `schema_drift`, `success_with_fallback` |
| `--id` | — | Show full multi-agent trace tree for one session |
| `--json` | false | Output as JSON |

<Warning>
`langsight sessions` requires the ClickHouse backend. The default storage mode `dual` includes ClickHouse — start it with `docker compose up -d`. If using `mode: postgres` only, the command prints: `No session data found. Sessions require the ClickHouse backend. See docs for setup.`
</Warning>

## Session list

```bash
langsight sessions --window 7d
```

```
Agent Sessions  (last 168h — 42 sessions)
────────────────────────────────────────────────────────────────────────────────────────────────────
Session ID                           Agent            Calls  Failed  Health          Duration  Servers
a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6  research-agent      24       1  tool_failure      14.2s  jira-mcp, confluence-mcp
b7e9d4c3-2f5e-4b9g-9d0e-8c3f6g1e2b7  data-pipeline        8       0  success            3.1s  postgres-mcp
c1a2b3d4-3g6f-4c0h-0e1f-9d4g7h2f3c8  support-agent       31       3  loop_detected     22.8s  jira-mcp, slack-mcp, s3-mcp
d5b6c7e8-4h7g-4d1i-1f2g-0e5h8i3g4d9  code-reviewer       12       0  success            5.6s  github-mcp, postgres-mcp
e9c0d1f2-5i8h-4e2j-2g3h-1f6i9j4h5e0  research-agent      18       2  budget_exceeded   11.4s  confluence-mcp, s3-mcp
```

Filter by health tag:

```bash
langsight sessions --health-tag loop_detected
```

## Single-session trace tree

Use `--id` to drill into a session and see the full multi-agent call tree:

```bash
langsight sessions --id a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6
```

```
Session a3f1c2b0  research-agent  24 calls  1 failed  14.2s

research-agent
├── 🤖 agent_start                                           0ms
├── 🔧 jira-mcp / search_issues        ✓  342ms
├── 🔧 jira-mcp / get_issue            ✓   89ms
├── 🔧 confluence-mcp / search         ✓  214ms
├── → handoff: research-agent → summarizer-agent
│   ├── 🤖 agent_start                                       0ms
│   ├── 🔧 confluence-mcp / get_page   ✓  178ms
│   ├── 🔧 confluence-mcp / get_page   ✓  163ms
│   └── 🤖 agent_end                                      1241ms
├── 🔧 jira-mcp / create_issue         ✓  411ms
├── 🔧 slack-mcp / post_message        ✗  timeout         5000ms
│   └── error: connection timeout after 5000ms
└── 🤖 agent_end                                         14200ms
```

Legend:
- `🤖` agent lifecycle span (start / end)
- `🔧` tool call span
- `→` handoff — agent-to-agent delegation
- `✓` success, `✗` failure

## Filter by agent

```bash
langsight sessions --agent research-agent --window 24h
```

## JSON output

```bash
langsight sessions --json --window 7d
```

Returns a JSON array of session objects:

```json
[
  {
    "session_id": "a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6",
    "agent_name": "research-agent",
    "first_call_at": "2026-03-17T09:14:02Z",
    "last_call_at": "2026-03-17T09:14:16Z",
    "tool_calls": 24,
    "failed_calls": 1,
    "duration_ms": 14200,
    "servers_used": ["jira-mcp", "confluence-mcp", "slack-mcp"],
    "health_tag": "tool_failure"
  }
]
```

For a single session with `--id --json`, the response includes the full span tree with `parent_span_id` fields.

## Requirements

Sessions are recorded by the LangSight SDK or any OTLP-instrumented framework:

```python
from langsight.sdk import LangSightClient

client = LangSightClient(url="http://localhost:8000")
mcp = client.wrap(
    your_mcp_client,
    server_name="jira-mcp",
    agent_name="research-agent",
    session_id="sess-f2a9b1",
)
result = await mcp.call_tool("search_issues", {"query": "refund policy"})
```

See the [SDK quickstart](/quickstart) and the [Python SDK guide](/sdk/python) for full setup instructions.

## Storage backend

| Backend | Sessions support | Notes |
|---------|-----------------|-------|
| `dual` (default) | Yes | Full support — Postgres metadata + ClickHouse `mv_agent_sessions` |
| `clickhouse` only | Yes | Full support — `mv_agent_sessions` materialized view pre-aggregates session metrics |
| `postgres` only | No | No session aggregation without ClickHouse |

Start the full stack with `docker compose up -d` (default `mode: dual`).

## Dashboard features

The `langsight sessions` CLI shows a summary. For full session debugging, open the dashboard (port `3003`):

- **Session detail page** — click any row in the Sessions table to open `/sessions/<id>`
- **Details tab** — timeline + interactive lineage graph + node/edge inspector
- **Trace tab** — nested span tree with inline payloads and LLM prompt/completion panels
- **Compare** — open a session, then compare it with another recent session
- **Replay** — replay tool calls from the session detail page against live MCP servers

See [Session Replay](/session-replay) for details.
