Traces

Every governance decision Palveron makes — verify, MCP tool call, approval, lifecycle transition — becomes a trace. Traces are append-only, hashed, and (when enabled) anchored on Flare for tamper-evidence.

GET /api/v1/traces

List traces with filters.

GET /api/v1/traces?time_range=7d&decision=BLOCKED&agent_id=ckagent...

Query	Default	Values
`time_range`	— (no time filter)	`24h`, `7d`, `30d`, `all`. Absent or `all` = no time filter. Invalid values return `400`.
`since` / `until`	—	ISO 8601 timestamps (e.g. `2026-03-19T00:00:00Z`) for custom windows
`decision`	—	`PASSED`, `FLAGGED`, `BLOCKED`, `MODIFIED`, `PENDING_APPROVAL`, `POLICY_CHANGE` (plus legacy row values `ALLOWED`, `ERROR`). Invalid values return `400`.
`agent_id`	—	Filter by agent
`environment` (alias `env`)	`prod`	Environment scope — note the default: without this parameter you only see `prod` traces
`id`	—	Exact trace-id lookup (returns that single trace regardless of age)
`limit`	`100`	Page size, max `1000`
`offset`	`0`	Offset-based pagination

{
  "traces": [
    {
      "id": "cktrace...",
      "sequence_num": 1042,
      "timestamp": "2026-05-15T14:23:00Z",
      "decision": "BLOCKED",
      "reason": "PII detected: SSN",
      "integrity_hash": "sha256:...",
      "flare_status": "ANCHORED",
      "flare_tx_hash": "0x...",
      "action_name": "VEXIS_NEURAL_VERIFY",
      "environment": "prod",
      "display_content": "",
      "content_state": "not_transmitted",
      "raw_available": true,
      "input_prompt": "",
      "output_response": null,
      "metadata": { "agent_id": "ckagent..." },
      "userAction": null,
      "justification": null
    }
  ],
  "total": 1
}

Pagination is offset-based (limit + offset); the response carries the matching total.

Trace content: what this endpoint does and does not return

The list never carries raw prompt content. Every row is resolved server-side into three fields, and the legacy fields are scrubbed to match:

Field	Meaning
`display_content`	The transmitted, display-safe text: the masked form for `REDACTED` / `ANONYMIZED` / `MODIFIED`, the clean prompt for `PASSED` / `FLAGGED`, and an empty string when nothing left the gateway.
`content_state`	`transmitted_masked`, `transmitted_plain`, `not_transmitted` (blocked or awaiting approval — the case above) or `unavailable` (a masked form should exist but could not be resolved; the raw input is never substituted).
`raw_available`	Whether a raw original exists that an admin could reveal through the gated reveal endpoint.

Consequently input_prompt carries the same safe value as display_content, and output_response is always null on this route. The raw original ships only via GET /api/v1/traces/{trace_id}/reveal, which is ADMIN-only, requires the project's audit detail level to be full, and writes an audit record on every successful reveal. extracted_text, the text taken from attachments, is always null for REDACTED, ANONYMIZED and MODIFIED.

Fetch a single trace

There is no /traces/{id} route — use the exact-id filter instead:

GET /api/v1/traces?id=cktrace...

Returns the full trace record including input/output payloads (subject to redaction rules), Flare proof fields, and any recorded user action.

POST /api/v1/traces/{trace_id}/action

Record a reviewer's decision on a trace flagged for manual review.

{ "action": "JUSTIFIED", "justification": "False positive — internal test data." }

Valid actions: WARN_PROCEEDED, JUSTIFIED. JUSTIFIED requires a justification of at least 10 characters. Each action writes an append-only, tamper-evident audit record.

GET /api/v1/export

Bulk export traces as CSV.

Query	Default	Description
`format`	`csv`	Only `csv` is supported — any other value returns `400`
`decision`	—	Same values and validation as `GET /traces`
`time_range`	— (no time filter)	`24h`, `7d`, `30d`, `all` — invalid values return `400`

Returns text/csv. These are the only filters the export applies — unsupported filter values fail loudly with 400 instead of silently delivering an unfiltered "filtered" export. If the export hits the row cap, the file ends with an explicit # truncated: … marker line.

How far back an export can reach is governed by the project's data-retention setting: trace content past min(configured retention, tier cap) is deleted by the retention worker. Exports cover what is retained.

Retry behavior

GET /traces and GET /export are idempotent — safe to retry. The SDKs retry transient 5xx and timeout errors up to maxRetries (default 3) with exponential backoff plus jitter. 429 responses include a Retry-After header; honor it.