Traces
Query the tamper-evident audit trail of governance decisions.
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 |
policy_id | — | Only traces where this policy triggered |
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",
"input_prompt": "…",
"output_response": "…",
"metadata": { "agent_id": "ckagent..." },
"user_action": null,
"justification": null
}
],
"total": 1
}Pagination is offset-based (limit + offset); the response carries the matching total.
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.