Traces

Den manipulationserkennenden 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
`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",
      "display_content": "",
      "content_state": "not_transmitted",
      "raw_available": true,
      "input_prompt": "",
      "output_response": null,
      "metadata": { "agent_id": "ckagent..." },
      "userAction": null,
      "justification": null
    }
  ],
  "total": 1
}

Die Paginierung ist offset-basiert (limit + offset); die Response trägt das passende total.

Trace-Inhalt: was dieser Endpunkt liefert und was nicht

Die Liste trägt niemals rohen Prompt-Inhalt. Jede Zeile wird serverseitig in drei Felder aufgelöst, und die Altfelder werden passend bereinigt:

Feld	Bedeutung
`display_content`	Der übertragene, anzeigesichere Text: die maskierte Form bei `REDACTED` / `ANONYMIZED` / `MODIFIED`, der saubere Prompt bei `PASSED` / `FLAGGED`, und eine leere Zeichenkette, wenn nichts das Gateway verlassen hat.
`content_state`	`transmitted_masked`, `transmitted_plain`, `not_transmitted` (blockiert oder in Freigabe — der Fall oben) oder `unavailable` (eine maskierte Form müsste existieren, ließ sich aber nicht auflösen; der rohe Eingabetext wird nie ersatzweise eingesetzt).
`raw_available`	Ob ein rohes Original existiert, das eine Administratorin über den gegateten Reveal-Endpunkt einsehen könnte.

Entsprechend trägt input_prompt denselben sicheren Wert wie display_content, und output_response ist auf dieser Route immer null. Das rohe Original gibt es ausschließlich über GET /api/v1/traces/{trace_id}/reveal — nur für ADMIN, nur wenn die Audit-Detailtiefe des Projekts auf full steht, und jede erfolgreiche Einsicht wird auditiert. extracted_text, der Text aus Anhängen, ist bei REDACTED, ANONYMIZED und MODIFIED immer null.

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, manipulationserkennenden 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.