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=agent_...| Query | Default | Values |
|---|---|---|
time_range | 24h | 1h, 24h, 7d, 30d, all |
from / to | — | ISO 8601 — overrides time_range for custom windows |
decision | — | PASSED, BLOCKED, MODIFIED, ERROR |
agent_id | — | Filter by agent |
policy_id | — | Only traces where this policy triggered |
trace_type | — | VERIFY, MCP_TOOL_CALL, BROWSER_SHIELD, LIFECYCLE |
cursor | — | Opaque pagination token from a previous response |
limit | 50 | Page size, max 200 |
Response includes a next_cursor field; pass it as cursor on the next request to page forward.
{
"traces": [
{
"id": "trc_01HVB...",
"trace_type": "VERIFY",
"agent_id": "agent_...",
"decision": "BLOCKED",
"reason": "PII detected: SSN",
"integrity_hash": "sha256:...",
"flare_tx_hash": "0x...",
"occurred_at": "2026-05-15T14:23:00Z",
"latency_ms": 87
}
],
"next_cursor": "eyJ0cyI6..."
}GET /api/v1/traces/{id}
Returns the full trace including: input/output payloads (subject to redaction rules), NGE scores, matched policies, user actions, and Flare proof.
POST /api/v1/traces/{id}/action
Record a reviewer's decision on a trace flagged for manual review.
{ "action": "WARN_PROCEEDED", "justification": "False positive — internal test data." }Valid actions: WARN_PROCEEDED, JUSTIFIED, REJECTED. Each writes an append-only, tamper-evident audit record.
GET /api/v1/export
Bulk export traces as CSV. Accepts the same filters as GET /api/v1/traces plus:
| Query | Default | Description |
|---|---|---|
format | csv | csv or ndjson |
fields | — | Comma-separated whitelist (e.g. id,decision,occurred_at) |
Returns text/csv (or application/x-ndjson). For exports over 100k rows the response is streamed.
Need months of history? Use time_range=all plus from/to to scope precisely. Exports are tier-limited: Community 30 days, Pro 90 days, Business 1 year, Enterprise unlimited.
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.