Audit trail#

Every action against the platform is recorded. Not a sample, not the successes — every call, allowed and denied, from every surface.

This is what makes "what did that agent do last night" a query.

Query it#

APIAgent

curl -fsS -G -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs/$ORG_ID/audit-trail \
  -d actorType=sandbox -d result=failure -d limit=100

Query the audit trail for the acme org. Show me every failed action
by a sandbox in the last 24 hours, grouped by what it was trying to
reach.

The agent calls query_audit_trail, get_audit_stats, and get_audit_timeseries. See Platform tools.

The admin UI renders the same data with statistics, an activity timeline, and a filterable event log.

Filters#

Parameter	Values
`actorType`	`user`, `agent`, `sandbox`, `system`, `cluster-jwt`
`actorId`	A specific actor
`source`	`rest-api`, `mcp-tool`, `k8s-proxy`, `forward-proxy`, `sandbox-proxy`, `aws-proxy`, `llm-proxy`
`action`	The action performed
`resourceType` / `resourceId`	What was acted on
`result`	`success`, `failure`, `error`
`projectId`	One project
`startTime` / `endTime`	ISO 8601 bounds
`limit`	Up to 200, 50 by default
`cursor`	ISO 8601 timestamp from the previous response

Two companion endpoints answer aggregate questions without paging everything:

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  "https://agents.example.com/v1/orgs/$ORG_ID/audit-trail/stats"

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  "https://agents.example.com/v1/orgs/$ORG_ID/audit-trail/timeseries"

What an entry contains#

Field	Meaning
`eventTime`, `durationMs`	When, and how long it took.
`actorType`, `actorId`, `actorName`	Who.
`authType`	How they authenticated — OIDC, API token, cluster JWT, sandbox.
`source`	Which surface the call arrived on.
`action`	What was attempted.
`resourceType`, `resourceId`	What it was attempted against.
`result`, `statusCode`	Whether it worked.
`orgId`, `projectId`	Where.
`metadata`	Source-specific detail.

The source field is what makes this useful in practice. A single agent session produces mcp-tool entries for tool calls, sandbox-proxy entries for its outbound HTTP, k8s-proxy entries for cluster calls, and llm-proxy entries for model requests — the same actor, seen through every boundary it crossed.

Denials are recorded too#

A policy denial is an audit event, not a silent drop. That turns two awkward questions into queries:

# What is my agent being blocked from reaching?
curl -fsS -G -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs/$ORG_ID/audit-trail \
  -d actorType=sandbox -d result=failure

# Has anything tried to reach a system it should not?
curl -fsS -G -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs/$ORG_ID/audit-trail \
  -d source=sandbox-proxy -d result=failure

The first is debugging: usually a missing domain in a policy. The second is security: an agent repeatedly probing something it was never granted is worth a look.

Attribution is per principal#

Because users, API tokens, and sandboxes are separate principals, the trail never merges them. A person, a token they created, and a sandbox they launched are three actors. "Who did this" has one answer, and revoking one identity does not disturb the others.

Common queries#

# Everything one sandbox did, newest first
...?actorId=$SANDBOX_ID

# Every model call in a project last week
...?source=llm-proxy&projectId=$PROJECT_ID&startTime=2026-08-01T00:00:00Z

# Every administrative change, regardless of surface
...?actorType=user&resourceType=policy

# Every cluster write
...?source=k8s-proxy&result=success

Export#

The query endpoint paginates by cursor, so a scheduled job can pull new entries into your SIEM or data warehouse on whatever cadence you keep. The audit trail lives in the platform's database, inside your cluster — retention is your storage policy, not a vendor's.

For platform-level operational telemetry, which is a different thing entirely, see Product telemetry.

Identity — why attribution is per principal
Policies — what produces the allows and denies
Spending limits — cost attribution from the same events
Compliance — how the trail supports audit obligations