Audit Logs

Thallus records an immutable audit trail for all significant actions — authentication, queries, agent operations, admin changes, and more. Admins can query, filter, and export these logs for compliance and debugging.

What gets logged

Every audit log entry contains:

Field Description
action What happened (e.g., login, query, tool_call)
user_id Who performed the action (null for system actions)
outcome Result: success, failure, partial, or denied
resource_type Type of resource affected (e.g., "document", "agent")
resource_id ID of the specific resource
correlation_id Links all operations in a single request chain
conversation_id Associated conversation (if applicable)
details Action-specific metadata (JSON)
ip_address Client IP address
duration_ms How long the action took
created_at Timestamp (UTC)

Outcomes

success failure partial denied
Outcome Meaning
success Action completed normally
failure Action failed (error details in error_message)
partial Action partially completed (e.g., some agents succeeded, others failed)
denied Action was blocked by access control

Querying logs

Admins can filter logs using any combination of:

Filter Description
user_id Logs for a specific user
action Single action type (e.g., login)
actions Multiple action types
outcome Filter by outcome
correlation_id All operations in a request chain
conversation_id All activity in a conversation
resource_type / resource_id Activity on a specific resource
start_date / end_date Time range

Results are paginated (default 100, max 1000 per page).

Correlation chains

Every API request gets a correlation_id. All operations triggered by that request — mode detection, planning, agent execution, tool calls, synthesis — share the same correlation ID.

query
→
mode_detection
→
plan_created
→
agent_execution ×3
→
response_synthesis

Query by correlation ID to see every step in a request's lifecycle. This is invaluable for debugging why a query produced unexpected results.

Access control

Role What they can see
Admin All logs in the system
Group admin Own logs + logs of group members
User Own logs only

Non-admin users can only see their own activity. Group admins get expanded visibility to help manage their teams.

Statistics

Admins can view aggregate statistics:

  • By action — Breakdown of log count per action type
  • By outcome — Success/failure/partial/denied distribution
  • Top users — Most active users by log count (admin only)
  • Time-filtered — All stats support start_date/end_date filtering

Exporting

Admin CSV export

Admins can export filtered audit logs as CSV with timezone conversion. The export uses the requesting admin's timezone preference for date formatting.

User self-service export

Users can export their own activity logs in CSV or JSON format:

Format Content
CSV Date, action, description, AI reasoning, outcome, duration, conversation
JSON Same fields in structured JSON format

Both formats support filtering by conversation, category, date range, and whether to include AI reasoning details.

User self-service

Users have dedicated endpoints for viewing their own activity without needing admin access:

MY ACTIVITY
Research query
2 min ago
Document uploaded
15 min ago
Login (SSO)
1 hr ago

Self-service features include: - Human-readable formatting — Action titles and descriptions instead of raw action codes - Category filtering — Filter by planning, agents, queries, integrations, etc. - Personal stats — Activity counts by category, outcome, and day - Conversation activity — See which conversations had the most activity

Retention

Setting Value
Default retention 90 days
Minimum 7 days
Maximum 5 years (1,825 days)

Admins can run retention cleanup with a dry-run option that shows how many logs would be deleted without actually removing them. Age distribution stats are available to understand the retention impact.

For GDPR compliance, admins can delete all audit logs for a specific user. This permanently removes the user's audit trail from the system.