Sessions

Enterprise only. Session forensics endpoints are available in Govrix Enterprise only. Scout OSS records session_id on every event and you can query by session via GET /api/v1/events/sessions/{session_id}, but the dedicated session index and aggregated session objects are Enterprise features.

Sessions group all events from a logical agent conversation. Each session carries a full audit trail with SHA-256 Merkle lineage hashes linking every event to its causal predecessor — enabling tamper-evident forensics for compliance and incident investigation.

`GET /api/v1/sessions`

List all sessions recorded by the proxy, ordered by started_at descending.

Auth required: Yes


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/sessions

Response 200 OK:


[
  {
    "id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
    "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "agent_name": "billing-agent",
    "started_at": "2026-03-05T14:20:00Z",
    "ended_at": "2026-03-05T14:20:45Z",
    "duration_ms": 45000,
    "event_count": 6,
    "total_tokens": 3840,
    "total_cost_usd": 0.02304,
    "compliance_tag": "default",
    "pii_detected": false
  },
  {
    "id": "ses_08qb6g9r0ux1v2w3y4z5a7b8c",
    "agent_id": "agt_02jy0a3l4nr5o6q7s8t9u1w2x",
    "agent_name": "support-agent",
    "started_at": "2026-03-05T14:21:00Z",
    "ended_at": "2026-03-05T14:22:30Z",
    "duration_ms": 90000,
    "event_count": 4,
    "total_tokens": 5050,
    "total_cost_usd": 0.01848,
    "compliance_tag": "default",
    "pii_detected": true
  }
]

Fields:

Field	Type	Description
`id`	string	Session ID (prefix `ses_`)
`agent_id`	string	Agent that owns this session
`agent_name`	string	Human-readable agent name
`started_at`	string	UTC timestamp of first event in session
`ended_at`	string	UTC timestamp of last event in session
`duration_ms`	integer	Wall-clock duration from first to last event
`event_count`	integer	Total events in the session
`total_tokens`	integer	Aggregate tokens across all turns
`total_cost_usd`	float	Aggregate USD cost for the session
`compliance_tag`	string	Policy label (inherited from events)
`pii_detected`	boolean	`true` if any event in the session flagged PII

`GET /api/v1/sessions/{id}`

Retrieve a session object together with its complete ordered event list. Use this for incident investigation and compliance audits.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Session ID (prefix `ses_`)


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/sessions/ses_07pa5f8q9tw0u1v2x3y4z5a6b

Response 200 OK:


{
  "session": {
    "id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
    "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "agent_name": "billing-agent",
    "started_at": "2026-03-05T14:20:00Z",
    "ended_at": "2026-03-05T14:20:45Z",
    "duration_ms": 45000,
    "event_count": 2,
    "total_tokens": 640,
    "total_cost_usd": 0.00384,
    "compliance_tag": "default",
    "pii_detected": false
  },
  "events": [
    {
      "id": "evt_03kz1b4m5os6p7r8t9u0v2x3y",
      "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
      "session_id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
      "timestamp": "2026-03-05T14:20:00Z",
      "direction": "request",
      "model": "gpt-4o",
      "prompt_tokens": 512,
      "completion_tokens": 0,
      "total_tokens": 512,
      "cost_usd": 0.0,
      "compliance_tag": "default",
      "lineage_hash": "sha256:a3f1c2d4e5b67890abcd1234ef567890abcd1234ef567890abcd1234ef567890",
      "pii_detected": false,
      "pii_types": []
    },
    {
      "id": "evt_04la2c5n6pt7q8s9u0v1w3y4z",
      "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
      "session_id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
      "timestamp": "2026-03-05T14:20:02Z",
      "direction": "response",
      "model": "gpt-4o",
      "prompt_tokens": 512,
      "completion_tokens": 128,
      "total_tokens": 640,
      "cost_usd": 0.00384,
      "compliance_tag": "default",
      "lineage_hash": "sha256:b4e2d3f5a6c7891bcde2345fg678901bcde2345fg678901bcde2345fg678901b",
      "pii_detected": false,
      "pii_types": []
    }
  ]
}

Response 404 Not Found:


{ "error": "session not found" }

The lineage_hash on each event is a SHA-256 Merkle hash computed as SHA256(prev_hash || event_payload). The root event uses SHA256("genesis" || event_payload). This chain can be verified offline to detect any post-hoc tampering with the event record.