> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Turn Audit: Verbatim AI Decision Records

> Tenant-owned verbatim logging of every AI agent turn — the evidence chain behind SOC2 / HIPAA / FINRA periodic export and GDPR Article 22 § 3 human-override stamping.

# AI Turn Audit: Verbatim AI Decision Records

AI Turn Audit records every completed AI agent turn — the system
prompt, the user prompt, and the assistant response, stored verbatim
alongside model, tokens, latency, retrieval and tool-call references —
into an append-only evidence log scoped to your tenant. It backs SOC2 /
HIPAA / FINRA evidence requests and implements the GDPR Article 22 § 3
human-override path for contested automated decisions.

<Warning>
  This page describes Orbit's platform controls. It is **not legal
  advice.** Whether your posture requires verbatim AI records depends on
  your regulator, your counsel, and your data-handling policy. The
  control is tenant-owned: you opt in, you opt out, and you own the
  retention decision.
</Warning>

***

## What this control does — and why it is fail-closed

When enabled, every completed AI agent turn writes one immutable row to
your tenant audit table with:

* the full system prompt and user prompt as sent to the model (verbatim,
  unredacted — a regulator must be able to reproduce the decision
  context),
* the final assistant response,
* model and version, token counts, latency, confidence, and the outcome
  (`ok`, `escalated`, `refused`, `error`, `cost_capped`),
* retrieval references (document name, score) and tool-call references
  (name, status, duration).

**Default OFF.** An org that never opts in records no verbatim turns.
The toggle is **fail-closed by design**: a lookup error reads as
disabled, so a transient storage problem never implies verbatim prompt
logging is on. Agent replies are never blocked by the audit write —
a failed write is logged and swallowed.

Verbatim prompt records are a PII surface under multi-year retention.
Treat enabling as a deliberate, policy-backed choice — and pair it with
a [retention decision](/compliance/data-retention-policy).

***

## Enable and disable (the Settings toggle)

The on/off switch lives at **Settings → Compliance → AI Turn Audit** in
the dashboard, or over the API on the Settings surface:

```bash theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/settings/compliance/ai-turn-audit" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

```json theme={null}
{
  "data": { "enabled": true }
}
```

To opt in (owner-only — the opt-in is an org-owner compliance decision):

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/compliance/ai-turn-audit" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

To disable later, re-run the same PUT with `enabled: false`. Every
change is written to the org audit log.

Distinguish the two endpoints that share a shape:

| Endpoint                                            | What it touches                        | Role                                          |
| --------------------------------------------------- | -------------------------------------- | --------------------------------------------- |
| `GET/PUT /api/v1/settings/compliance/ai-turn-audit` | The org **toggle** — whether to record | PUT is owner-only; GET readable by any member |
| `GET /api/v1/agents/ai-turn-audit`                  | The **recorded rows** themselves       | Owner or admin                                |

***

## Filter and paginate the recorded turns

`GET /api/v1/agents/ai-turn-audit` returns rows newest-first with
cursor pagination. Filter by agent, conversation, or a date range
(common windows: day, week, quarter — a day range is
`from=2026-08-29` → `to=2026-08-30`).

```bash theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/agents/ai-turn-audit?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

```json theme={null}
{
  "data": {
    "rows": [
      {
        "id": "a9e7f47c-…",
        "conversation_id": "conv_9m2hj",
        "agent_id": "agt_support1",
        "model": "claude-sonnet-4-6",
        "model_version": null,
        "system_prompt": "You are a support agent for …",
        "user_prompt": "My invoice shows the wrong VAT.",
        "assistant_response": "Let me pull up the invoice …",
        "retrieval_refs": [],
        "tool_call_refs": [
          { "toolName": "get_invoice", "status": "ok", "durationMs": 412 }
        ],
        "confidence": 0.93,
        "outcome": "ok",
        "prompt_tokens": 1820,
        "completion_tokens": 214,
        "latency_ms": 1340,
        "request_id": "req_…",
        "human_override_user_id": null,
        "human_override_reason": null,
        "human_override_at": null,
        "created_at": "2026-08-29T11:22:41.319Z"
      }
    ],
    "next_cursor": "2026-08-29T11:22:41.319Z|a9e7f47c-…",
    "count": 200
  }
}
```

Pass `next_cursor` back as `cursor` and repeat until `next_cursor` is
`null` — the chain is deterministic so a same-millisecond batch never
re-orders mid-export. Page size is clamped to 1–200 rows (default 50).

Two narrower views:

* **One conversation:** `GET /api/v1/agents/conversations/{conversationId}/ai-turn-audit`
  — the per-conversation evidence chain behind the dashboard's
  chain-of-decisions panel.
* **DSAR (Art. 15):** enumerate the subject's conversations and pull
  each through the per-conversation route; see [DSAR](/compliance/dsar).

Full request/response schema:
[API Reference → Agents](/api-reference/endpoints/agents).

***

## Record a GDPR Art-22 § 3 human override

When a human contests an automated decision, stamp the audit row with
an override — the original decision is preserved; the override appends
a second stamp rather than mutating the row.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/agents/ai-turn-audit/a9e7f47c-…/override" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer disputes the automated refund refusal — reviewed by operator sara.k, ticket T-11452, Art-22 § 3 contest upheld"
  }'
```

Constraints:

* The `auditId` path segment is the row's UUID.
* `reason` is free text, 1–2000 characters, trimmed server-side.
* **Append-once:** a second override on the same row returns
  `409 OVERRIDE_ALREADY_APPLIED`; an unknown id returns
  404 `AUDIT_ROW_NOT_FOUND`.
* Access is owner/admin — the same gate as the tenant export.

In the dashboard the override is recorded from the expanded row under
**Settings → Compliance → AI Turn Audit** — the "Record human override"
button opens the same dialog with the same append-once semantics.

***

## Periodic export — JSONL with a 5000-row soft cap

The canonical SOC2 / HIPAA / FINRA evidence pull exports the filtered
set as JSON Lines — one audit row per line, bit-for-bit the same row
shape the API returns (no field renaming, no row-shape coercion).

In the dashboard an **Export JSONL** button in the page header walks
the cursor until exhausted and downloads `ai-turn-audit-<date>.jsonl`.
Over the API you do the same: page through `next_cursor` at up to 200
rows per call and write one row per line.

The dashboard export applies a **soft cap of 5000 rows** so a
misclicked unfiltered range cannot run away. If your export hits the
cap, narrow the date range or the agent/conversation filter and
re-run the remainder — needed, for example, on quarterly FINRA
reviews of high-volume tenants.

***

## When to leave it off vs on

**Leave it OFF (the default)** unless your policy literally requires
verbatim AI records. This is the fail-safe direction for ordinary
SMB, marketing, or support workloads — enabling costs write
amplification and a multi-year PII surface a casual tenant doesn't
want.

**Turn it ON** when your audit policy requires verbatim evidence:

* **HIPAA** — healthcare tenants under an executed BAA whose
  data-handling rules mandate verbatim decision records. Pair with
  closing the [inbox AI privacy gates](/compliance/hipaa) and a
  [retention window](/compliance/data-retention-policy); see
  [Posture D in the posture map](/compliance/posture-overview#posture-d-regulated-healthcare-sender).
* **SOC2** — control-evidence for CC-series change-management and
  incident-review controls; pair with the [archival export](/compliance/archival-export)
  binder and the [SOC2 controls page](/compliance/soc2-controls).
* **FINRA** — broker-dealer review of automated decisioning; the
  periodic JSONL export is the artifact reviewers expect.

"Off by accident" and "on by accident" are both findings in a
compliance review — decide explicitly and record it in your
[posture binder](/compliance/evidence-binder).

***

## Related references

* [Posture overview](/compliance/posture-overview) — the toggle map:
  where AI-turn audit sits in the whole control surface.
* [HIPAA](/compliance/hipaa) — BAA, HIPAA mode, the inbox AI gates.
* [SOC2 controls](/compliance/soc2-controls) — control-evidence export.
* [Data retention policy](/compliance/data-retention-policy) — the
  retention window for verbatim prompt rows.
* [DSAR](/compliance/dsar) — Art. 15 export per data subject.
* [Evidence binder](/compliance/evidence-binder) — hands the whole
  posture to a buyer or authority.
* [Compliance health](/compliance/compliance-health) — the read-only
  safety layer.