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

# Trace: compliance guardrails

> Score eligible calls against compliance rule packs, get a tamper-evident scorecard per scanned call, and read your org's exposure.

**Trace** scores the call you already ran. It is not a second QA vendor and
not a pre-deploy simulation suite. Every scanned call gets a deterministic
**scorecard**: which rules fired, which requirements were satisfied, what was
redacted, and a verdict (`PASS`, `WARN`, `FAIL`), with plain-English reasons
and cited regulations, sealed with a tamper-evident `audit_hash`. A second,
asynchronous layer adds **semantic findings** (model-judged concerns
deterministic rules can't catch, like indirect opt-outs or
hallucination-vs-knowledge-base); those are advisory and never block.

<Note>
  Trace is in **beta**. Enable it deliberately for your organization; current
  terms and any promotional treatment are listed on the
  [pricing page](https://pyai.com/pricing). Findings are informational and not
  legal advice.
</Note>

You need a key with `trace:configure` (to manage config and rule packs) and
`trace:read` (to read results). Add scopes in the
[console](https://console.pyai.com).

## What Trace scans

Trace runs only when the call or transcription enters a Trace-enabled path:

* Omni and console Agent calls covered by an enabled organization or per-agent
  Trace config.
* Async Hear jobs that explicitly send `trace: true` and belong to an
  organization entitled for Trace on transcription. This single-pass path
  cannot be combined with `channel: true` or `diarize: true`. The job runs a
  deterministic PII scan over the final transcript (SSN, card numbers, CVV in
  context, email, US phone), redacts findings, and returns a `trace` summary.
* Certified inbound call imports whose integration guide explicitly includes a
  Trace scorecard, when Trace is enabled for the organization.

Creating a Hear transcript, connecting a CRM, or importing a call does not
silently enable paid Trace processing. If a source needs both diarization and
compliance analysis, confirm the supported pipeline before launch rather than
dropping speaker separation or scanning only one channel.

## Step 1, configure Trace

One `PUT` sets the org-wide default; add `?agent_id=` (or wrap the body as
`{ "agent_id", "config" }`) to override per agent:

```bash theme={null}
curl -X PUT https://api.pyai.com/v1/trace/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "rule_packs": {
      "tcpa": { "enabled": true },
      "pii":  { "enabled": true }
    },
    "guardrails": {
      "mode": "warn",
      "block_pii": { "patterns": ["ssn", "credit_card"] },
      "mandatory_disclosures": [
        { "text": "This call may be recorded.", "trigger": "call_start" }
      ]
    }
  }'
```

The response is the stored config with a content-addressed `ETag`, the runtime
pins it, so a config change takes effect on the next pull. `GET
/v1/trace/config` reads it back (omit `agent_id` for the org default).

### Pick a mode

| Mode | Behavior |
| - | - |
| `warn` | Log and score only. Never touches the call. Start here. |
| `modify` | Redact PII and inject missing disclosures inline. |
| `block` | Suppress non-compliant output. |
| `human_handoff` | Escalate the call to a human. |

Every mode is **fail-open**: if anything in the pipeline errors, the call
continues and the gap is recorded, compliance tooling never takes your agents
down.

## Step 2, know your rule packs

Built-in packs cover **TCPA**, **HIPAA**, **PII**, and **brand voice**. List
what's available (built-ins plus your tenant's custom packs):

```bash theme={null}
curl https://api.pyai.com/v1/trace/rule-packs \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

Pin a specific version in config with `"tcpa": { "enabled": true, "version":
"v3" }`, or omit `version` to track the latest active. You can also upload your
own pack in the Trace DSL (`POST /v1/trace/rule-packs` with `pack_id`,
`version`, and `rules[]`); custom packs are scoped to your org and can never
shadow a built-in.

## Step 3, read the results

All four reads are cursor-paginated and newest-first.

**Exposure summary**, the dashboard headline: interactions scanned, the share
with a compliance gap, per-rule exposure ranking, and the verdict mix over a
trailing window:

```bash theme={null}
curl "https://api.pyai.com/v1/trace/exposure?window_days=30" \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

**Interactions**, one scorecard row per call. Filter by `verdict`
(`PASS`/`WARN`/`FAIL`) or `agent_id`:

```bash theme={null}
curl "https://api.pyai.com/v1/trace/interactions?verdict=FAIL&limit=20" \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

**Interaction detail**, the full evidence view for one `call_id`: findings with
reasons and cited regulations, satisfied requirements, redactions, gate health,
the verdict, and the tamper-evident `audit_hash`:

```bash theme={null}
curl "https://api.pyai.com/v1/trace/interactions/<call_id>" \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

**Violations**, every fired rule across scorecards, for drill-down. Filter by
`rule_id`, `severity` (`low`/`medium`/`high`/`critical`), or `interaction_id`:

```bash theme={null}
curl "https://api.pyai.com/v1/trace/violations?severity=critical" \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

**Findings**, the async semantic layer (advisory, kept separate from the
hash-chained violations). Filter by `check_id`, `action`, or `severity`; the
compliance-officer alerts feed is `action=escalate` and/or
`severity=critical`:

```bash theme={null}
curl "https://api.pyai.com/v1/trace/findings?action=escalate" \
  -H "Authorization: Bearer $PYAI_API_KEY"
```

## The console view

The **Compliance / Trace** tab in the [console](https://console.pyai.com)
renders the same data, Overview (exposure), Interactions (scorecards), and
Alerts (escalated findings), no code required.

## Metering

Trace meters one `trace.calls` unit for each scanned call, on top of the
underlying call product. Current rates and any promotional billing appear on
the [pricing page](https://pyai.com/pricing) and in your console.

## Next steps

<CardGroup cols={2}>
  <Card title="Trace API reference" href="/api-reference">Full request/response schemas for every `/v1/trace/*` endpoint.</Card>
  <Card title="Post-call extraction" href="/guides/post-call-extraction">Pull structured data out of completed calls.</Card>
  <Card title="Conversation intelligence" href="/guides/conversation-intelligence">Recap: summaries and CRM sync for your calls.</Card>
  <Card title="Errors & limits" href="/errors-and-limits">Error codes, pagination, and idempotency conventions.</Card>
</CardGroup>

## Recurring issues and coverage

The Trace overview groups deterministic findings by check, showing affected
calls, affected agents, recent examples and the previous period's call count.
A call with several findings from the same check counts once. Open an example
to inspect its evidence and use the review inbox for ownership, comments and
resolution. Export matching issue rows as CSV.

Coverage includes retained PyAI call records, Recap calls and Trace records
received during the selected period. It distinguishes healthy reported checks,
limited checks, unknown check health and calls with no scorecard. This is a
retained-call denominator, not a promise that every call was eligible for Trace.
No scorecard can mean Trace was disabled or processing did not finish. Check
health is separate from the verdict: healthy checks can find failures.
Use **Scoring details & settings** for verdict totals and the organization default.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.