Session Report

llm-usage session lists usage per conversation (session) rather than per calendar period, so you can find your most expensive or most active sessions and where they ran.

Command structure

llm-usage session [options]

Examples:

llm-usage session
llm-usage session --top 50
llm-usage session --top 0
llm-usage session --id 486c3261
llm-usage session --by-repo
llm-usage session --source codex --json
llm-usage session --markdown

Options

• --top <n>: how many rows to show, ranked by cost (default 20; --top 0 shows all)
• --id <substring>: keep only sessions whose id contains the substring (case-insensitive, repeatable); cannot be combined with --by-repo
• --by-repo: aggregate sessions into one row per repository root
• shared filters apply: --source, --provider, --model, --since, --until, --timezone, source-path overrides, pricing flags, and --history

session supports terminal, --json, and --markdown output. It does not support --share.

Output

The terminal report is a boxed Session Usage Report table with Session, Source, Repo, Last Activity, Duration, Total, Cost, and Models columns, sorted by cost. Duration is the raw span from a session’s first to last event (- for single-event sessions). Sessions have no TOTAL row because each row is a conversation, not a calendar period. When the list is truncated, a note is printed on stderr:

Showing top 20 of 1653 sessions by cost. Use --top 0 for all.

--by-repo replaces the per-session rows with one row per repository (Repo, Sessions, Last Activity, Total, Cost, Sources). Sessions without a detectable repository are grouped under (no repo).

JSON shape

Default --json returns an array of session rows under data:

{
  "schemaVersion": 1,
  "report": "session",
  "data": [
    {
      "rowType": "session",
      "source": "codex",
      "sessionId": "486c3261-d87e-4971-8813-904c9e5a9009",
      "repoRoot": "/path/to/repo",
      "firstActivity": "2026-03-05T10:00:00.000Z",
      "lastActivity": "2026-03-05T11:30:00.000Z",
      "durationMs": 5400000,
      "activeMs": 2700000,
      "eventCount": 42,
      "models": ["gpt-5.1"],
      "inputTokens": 120000,
      "outputTokens": 8000,
      "reasoningTokens": 0,
      "cacheReadTokens": 40000,
      "cacheWriteTokens": 0,
      "totalTokens": 168000,
      "costUsd": 1.23
    }
  ]
}

durationMs is the raw span: lastActivity minus firstActivity; it over-counts idle time by design. activeMs is the honest “hands-on time”: the sum of inter-event gaps, each capped at 5 minutes, so a session left open overnight contributes at most 5 idle minutes per gap. Single-event sessions get activeMs: 0.

--by-repo --json returns an array of repo rows (rowType: "repo", repoRoot, sessionCount, firstActivity, sources, and the same token/cost totals).