Events

Every request proxied through Govrix Scout produces an event. Events are written fire-and-forget via a bounded mpsc channel (capacity 10,000) to a background batch writer (100 ms / 100 events) backed by a PostgreSQL TimescaleDB hypertable.

Compliance fields

Every event is guaranteed to carry four compliance fields, enforced at compile time in Rust:

Field	Description
`session_id`	Groups related requests into a logical session
`timestamp`	UTC ISO 8601, set at proxy ingress
`lineage_hash`	SHA-256 Merkle hash linking the event to its causal chain
`compliance_tag`	Policy label attached at proxy time (default: `"default"`)

`GET /api/v1/events`

List all events with optional filtering and pagination.

Auth required: Yes

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	`50`	Maximum events to return (max 1000)
`offset`	integer	`0`	Pagination offset
`agent_id`	string	—	Filter to a specific agent
`session_id`	string	—	Filter to a specific session


# Latest 20 events for a specific agent
curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  "http://localhost:4001/api/v1/events?limit=20&agent_id=agt_01hx9z2k3mq4n5p6r7s8t9u0v"

Response 200 OK:


[
  {
    "id": "evt_03kz1b4m5os6p7r8t9u0v2x3y",
    "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "session_id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
    "timestamp": "2026-03-05T14:20:00Z",
    "direction": "request",
    "model": "gpt-4o",
    "provider": "openai",
    "prompt_tokens": 512,
    "completion_tokens": 128,
    "total_tokens": 640,
    "cost_usd": 0.00384,
    "compliance_tag": "default",
    "lineage_hash": "sha256:a3f1c2d4e5b67890abcd1234ef567890abcd1234ef567890abcd1234ef567890",
    "pii_detected": false,
    "pii_types": []
  }
]

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

Retrieve a single event by its ID.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Event ID (prefix `evt_`)


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

Response 200 OK:


{
  "id": "evt_03kz1b4m5os6p7r8t9u0v2x3y",
  "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
  "session_id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
  "timestamp": "2026-03-05T14:20:00Z",
  "direction": "request",
  "model": "gpt-4o",
  "provider": "openai",
  "prompt_tokens": 512,
  "completion_tokens": 128,
  "total_tokens": 640,
  "cost_usd": 0.00384,
  "compliance_tag": "default",
  "lineage_hash": "sha256:a3f1c2d4e5b67890abcd1234ef567890abcd1234ef567890abcd1234ef567890",
  "pii_detected": false,
  "pii_types": []
}

Response 404 Not Found:


{ "error": "event not found" }

`GET /api/v1/events/sessions/{session_id}`

Retrieve all events belonging to a session, ordered by timestamp ascending. Use this to reconstruct the full turn-by-turn exchange for a session.

Auth required: Yes

Path parameters:

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


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

Response 200 OK:


[
  {
    "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,
    "cost_usd": 0.0,
    "compliance_tag": "default",
    "lineage_hash": "sha256:a3f1c2d4...",
    "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:b4e2d3f5...",
    "pii_detected": false,
    "pii_types": []
  }
]

`GET /api/v1/events/stream`

Server-Sent Events (SSE) stream of live events as they flow through the proxy. The connection stays open; each event is emitted as an SSE message.

Auth required: Yes

This is a long-lived HTTP connection. Reconnect with Last-Event-ID support is not yet implemented — clients should reconnect and backfill from /api/v1/events if needed.


curl -N \
  -H "Authorization: Bearer $GOVRIX_API_KEY" \
  -H "Accept: text/event-stream" \
  http://localhost:4001/api/v1/events/stream

Stream format:

Each SSE message has event: agent_event and a JSON data payload:


event: agent_event
data: {"id":"evt_05mb3d6o7qu8r9s0v1w2x4z5a","agent_id":"agt_01hx9z2k3mq4n5p6r7s8t9u0v","session_id":"ses_07pa5f8q9tw0u1v2x3y4z5a6b","timestamp":"2026-03-05T14:21:00Z","model":"gpt-4o","prompt_tokens":300,"completion_tokens":90,"cost_usd":0.00231,"compliance_tag":"default","lineage_hash":"sha256:c5f3e4g6...","pii_detected":false}

event: agent_event
data: {"id":"evt_06nc4e7p8rv9s0t1w2x3y5a6b","agent_id":"agt_02jy0a3l4nr5o6q7s8t9u1w2x","session_id":"ses_08qb6g9r0ux1v2w3y4z5a7b8c","timestamp":"2026-03-05T14:21:01Z","model":"claude-3-5-sonnet-20241022","prompt_tokens":800,"completion_tokens":250,"cost_usd":0.00915,"compliance_tag":"default","lineage_hash":"sha256:d6g4f5h7...","pii_detected":true,"pii_types":["email"]}

The stream emits a keepalive comment (: keepalive) every 15 seconds if no events occur.