---
name: vr-monitor-sessions
description: Monitor VoiceRun agent sessions, traces, spans, and usage. View call history, debug latency, analyze conversation quality, and track costs.
---

# Monitor VoiceRun Sessions and Usage

You are helping the user monitor their voice agent's sessions, traces, and usage data. This covers call history, debugging, and cost tracking. Follow this guide:

## Session Management (`vr session`)

### List sessions

View recent sessions for an agent:

```bash
vr session list <AGENT>
```

Filter and paginate results:

| Option | Description |
|--------|-------------|
| `--status`, `-s` | Filter by status (e.g., `completed`, `in_progress`) |
| `--direction`, `-d` | Filter by call direction (e.g., `inbound`, `outbound`) |
| `--limit`, `-l` | Limit number of results |
| `--page`, `-p` | Page number for pagination |
| `--json`, `-j` | Output as JSON |
| `--table`, `-t` | Output as table |

```bash
# List recent completed sessions
vr session list my-agent --status completed

# List inbound calls only
vr session list my-agent --direction inbound

# Paginate through results
vr session list my-agent --limit 20 --page 2

# Get JSON output for scripting
vr session list my-agent --json
```

### Session details

View detailed information about a specific session:

```bash
vr session info <AGENT> <SESSION_ID>
```

Shows: session ID, status, direction, environment, deployment, telephony call ID, usage, tags, and timestamps.

```bash
# Rich formatted output
vr session info my-agent <SESSION_ID> --table

# JSON output
vr session info my-agent <SESSION_ID> --json
```

### Traces

View the execution trace for a session as a span tree:

```bash
vr session trace <AGENT> <SESSION_ID>
```

Traces show the hierarchical execution flow of your agent, including:
- Handler invocations
- LLM calls and latency
- Tool executions
- TTS/STT processing times

```bash
# Tree view
vr session trace my-agent <SESSION_ID> --table

# JSON output for analysis
vr session trace my-agent <SESSION_ID> --json
```

**Note:** Tracing must be enabled in the agent's environment privacy settings.

### Span details

Drill into a specific span within a trace:

```bash
vr session span <AGENT> <SESSION_ID> <SPAN_ID>
```

Shows detailed attributes, timing, and status for a single span.

```bash
# Rich formatted view
vr session span my-agent <SESSION_ID> <SPAN_ID> --table

# JSON output
vr session span my-agent <SESSION_ID> <SPAN_ID> --json
```

## Usage Reports (`vr usage`)

### Custom date range report

View usage data for a specific date range:

```bash
vr usage report
```

| Option | Description |
|--------|-------------|
| `--start`, `-s` | Start date in YYYY-MM-DD format (default: 30 days ago) |
| `--end`, `-e` | End date in YYYY-MM-DD format (default: today) |
| `--by-tags` | Break down usage by session tags |
| `--tags` | Filter by specific tags (JSON format) |
| `--json`, `-j` | Output as JSON |
| `--table`, `-t` | Output as table |

```bash
# Last 30 days usage
vr usage report

# Specific date range
vr usage report --start 2026-01-01 --end 2026-01-31

# Break down by tags
vr usage report --by-tags

# Filter by specific tags
vr usage report --tags '{"campaign": "summer-promo"}'

# JSON output
vr usage report --json
```

### Monthly report

View usage for a specific month:

```bash
vr usage monthly
```

| Option | Description |
|--------|-------------|
| `--year`, `-y` | Year (default: current year) |
| `--month`, `-m` | Month 1-12 (default: current month) |
| `--by-tags` | Break down by session tags |
| `--tags` | Filter by specific tags (JSON format) |
| `--json`, `-j` | Output as JSON |
| `--table`, `-t` | Output as table |

```bash
# Current month
vr usage monthly

# Specific month
vr usage monthly --year 2026 --month 1

# With tag breakdown
vr usage monthly --by-tags
```

## Common Monitoring Workflows

### Investigate a failed call

```bash
# Find the session
vr session list my-agent --status completed --limit 10

# Get session details
vr session info my-agent <SESSION_ID> --table

# View the execution trace to find the failure point
vr session trace my-agent <SESSION_ID> --table

# Drill into a specific span for details
vr session span my-agent <SESSION_ID> <SPAN_ID> --table
```

### Debug latency issues

```bash
# View the trace tree to identify slow spans
vr session trace my-agent <SESSION_ID> --table

# Inspect the slowest span
vr session span my-agent <SESSION_ID> <SPAN_ID> --table
```

VoiceRun captures five per-turn latency metrics:
- **End-to-End Turn Taking** — Total time from user speech to audio playback
- **STT Latency** — Speech-to-text processing time
- **Handler Latency** — Your agent code execution time
- **LLM Latency** — Time waiting for LLM completions
- **TTS Latency** — Text-to-speech generation time

### Track costs over time

```bash
# Monthly cost overview
vr usage monthly

# Compare months
vr usage monthly --year 2026 --month 1
vr usage monthly --year 2026 --month 2

# Break down by campaign tags
vr usage report --start 2026-01-01 --end 2026-03-31 --by-tags
```

### Monitor production health

```bash
# Check recent sessions
vr session list my-agent --limit 20

# Filter for in-progress calls
vr session list my-agent --status in_progress

# Quick usage check
vr usage report --start 2026-03-25 --end 2026-03-26
```

## Web Dashboard

For a visual view of sessions, traces, recordings, and transcripts, open the VoiceRun web app:

- Sessions: `https://app.voicerun.com/agents/{agentId}/sessions`
- Open from CLI: `vr open`

## Troubleshooting

- **"Agent not found"** — Verify the agent name with `vr get agents`.
- **Empty session list** — The agent may not have received any calls yet, or filters may be too restrictive. Try without filters.
- **No trace data** — Tracing must be enabled in the agent's environment. Check with `vr describe environment <AGENT> <ENV>`.
- **"Session not found"** — Verify the session ID. Session IDs are UUIDs.
- **Usage shows zero** — Usage data is computed from daily summaries. Recent sessions may not appear until the next day.

Help the user find and analyze the session data they need.
