Audit Trail

Overview

System R maintains a complete audit trail of every billable event for each agent. Every deposit, tool call, and deduction is recorded with a timestamp, operation type, amount, and resulting balance.

Get audit trail

GET /v1/audit/trail

Parameters

Parameter	Type	Required	Description
from_date	string	No	ISO date start (e.g. "2026-01-01").
to_date	string	No	ISO date end (e.g. "2026-12-31").
limit	int	No	Max entries (1 to 1000, default 200).

Example

curl "https://agents.systemr.ai/v1/audit/trail?from_date=2026-03-01&to_date=2026-03-31&limit=50" \
  -H "X-API-Key: sr_agent_..."

Response

{
  "agent_id": "agt_a1b2c3d4",
  "from_date": "2026-03-01T00:00:00",
  "to_date": "2026-03-31T23:59:59",
  "total_calls": 142,
  "total_spend": "3.47",
  "entries": [
    {
      "timestamp": "2026-03-25T14:30:00",
      "action": "consumption",
      "operation": "pre_trade_gate",
      "amount": "0.01",
      "balance_after": "39.03"
    },
    {
      "timestamp": "2026-03-25T14:29:55",
      "action": "consumption",
      "operation": "calculate_position_size",
      "amount": "0.003",
      "balance_after": "39.04"
    },
    {
      "timestamp": "2026-03-25T10:00:00",
      "action": "deposit",
      "operation": null,
      "amount": "50.00",
      "balance_after": "42.50"
    }
  ],
  "entry_count": 3
}

Entry fields

Field	Description
timestamp	ISO timestamp of the event.
action	Event type: deposit, consumption, withdrawal, credit.
operation	Tool or operation name (null for deposits).
amount	Dollar amount of the event.
balance_after	Agent balance after this event.

Compliance check

GET /v1/audit/compliance-check

Runs a compliance analysis on the agent’s audit trail. Returns any flags found.

Example

curl https://agents.systemr.ai/v1/audit/compliance-check \
  -H "X-API-Key: sr_agent_..."

Response

{
  "agent_id": "agt_a1b2c3d4",
  "is_clean": true,
  "total_calls": 142,
  "total_spend": "3.47",
  "flags": [],
  "flag_count": 0
}

If issues are detected:

{
  "agent_id": "agt_a1b2c3d4",
  "is_clean": false,
  "total_calls": 5420,
  "total_spend": "312.50",
  "flags": [
    {
      "severity": "warning",
      "description": "High call volume in short period (>1000 calls/hour)",
      "timestamp": "2026-03-25T14:00:00"
    }
  ],
  "flag_count": 1
}

Flag severities

Severity	Meaning
info	Informational observation. No action needed.
warning	Unusual pattern detected. Review recommended.
critical	Potential issue requiring immediate attention.