Traces
Den manipulationssicheren Audit-Trail der Governance-Entscheidungen abfragen.
Jede Governance-Entscheidung von Palveron — Verify, MCP-Tool-Call, Freigabe, Lifecycle-Übergang — wird zu einem Trace. Traces sind append-only, gehasht und (wenn aktiviert) auf Flare verankert.
GET /api/v1/traces
Traces mit Filtern abfragen.
GET /api/v1/traces?time_range=7d&decision=BLOCKED&agent_id=ckagent...| Query | Default | Werte |
|---|---|---|
time_range | — (kein Zeitfilter) | 24h, 7d, 30d, all. Fehlend oder all = kein Zeitfilter. Ungültige Werte liefern 400. |
since / until | — | ISO-8601-Zeitstempel (z. B. 2026-03-19T00:00:00Z) für eigene Zeitfenster |
decision | — | PASSED, FLAGGED, BLOCKED, MODIFIED, PENDING_APPROVAL, POLICY_CHANGE (plus Legacy-Zeilenwerte ALLOWED, ERROR). Ungültige Werte liefern 400. |
agent_id | — | Nach Agent filtern |
policy_id | — | Nur Traces, bei denen diese Policy ausgelöst hat |
environment (Alias env) | prod | Umgebungs-Scope — Achtung Default: ohne diesen Parameter sind nur prod-Traces sichtbar |
id | — | Exakter Trace-ID-Lookup (liefert genau diesen Trace, unabhängig vom Alter) |
limit | 100 | Seitengröße, max. 1000 |
offset | 0 | Offset-basierte Paginierung |
{
"traces": [
{
"id": "cktrace...",
"sequence_num": 1042,
"timestamp": "2026-05-15T14:23:00Z",
"decision": "BLOCKED",
"reason": "PII erkannt: 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
}Die Paginierung ist offset-basiert (limit + offset); die Response trägt das passende total.
Einzelnen Trace abrufen
Es gibt keine /traces/{id}-Route — stattdessen den Exakt-ID-Filter nutzen:
GET /api/v1/traces?id=cktrace...Liefert den vollständigen Trace-Record inkl. Input-/Output-Payloads (vorbehaltlich Redaktionsregeln), Flare-Proof-Feldern und einer ggf. erfassten User-Action.
POST /api/v1/traces/{trace_id}/action
Die Entscheidung eines Reviewers zu einem markierten Trace erfassen.
{ "action": "JUSTIFIED", "justification": "False Positive — interne Testdaten." }Gültige Actions: WARN_PROCEEDED, JUSTIFIED. JUSTIFIED erfordert eine justification von mindestens 10 Zeichen. Jede Action schreibt einen append-only, manipulationssicheren Audit-Record.
GET /api/v1/export
Traces als CSV exportieren.
| Query | Default | Beschreibung |
|---|---|---|
format | csv | Nur csv wird unterstützt — jeder andere Wert liefert 400 |
decision | — | Gleiche Werte und Validierung wie bei GET /traces |
time_range | — (kein Zeitfilter) | 24h, 7d, 30d, all — ungültige Werte liefern 400 |
Liefert text/csv. Das sind die einzigen Filter, die der Export anwendet — nicht unterstützte Filterwerte schlagen laut mit 400 fehl, statt still einen ungefilterten „gefilterten" Export zu liefern. Erreicht der Export das Zeilen-Cap, endet die Datei mit einer expliziten # truncated: …-Markerzeile.
Wie weit ein Export zurückreicht, bestimmt die Datenaufbewahrungs-Einstellung des Projekts: Trace-Inhalte jenseits von min(konfigurierte Aufbewahrung, Tier-Cap) löscht der Retention-Worker. Exporte decken ab, was aufbewahrt ist.
Retry-Verhalten
GET /traces und GET /export sind idempotent — Retries sind sicher. Die SDKs wiederholen transiente 5xx- und Timeout-Fehler bis maxRetries (Default 3) mit Exponential Backoff plus Jitter. 429-Responses enthalten einen Retry-After-Header; diesen respektieren.