Skip to main content
Trace evaluates eligible calls against configured rules and returns scorecards, violations, and supporting evidence. Semantic findings are a separate advisory layer. Use Recap for summaries and action items. For transcript masking across Hear’s STT endpoints, see STT redaction; it does not require the Trace add-on.

Walkthrough: review an existing sales call

Inputs: an existing Trace interaction ID and a server-side key with trace:read in the authorized organization. Output: a JSON review containing the reported verdict, findings, reasons, citations, available timestamps, check health and audit hash. No new audio, transcription or scoring is submitted. Start with the existing Trace example. It now includes review-call.mjs alongside the dashboard. Requires Node 22 or later and no dependencies.

1. Run the fictional example without credentials

Open sample-review.json. It must contain sample: true, interaction_id: "sample-sales-call" and a clearly fictional opening-disclosure finding. The script makes no network requests in this mode, even if a key is already present. The fixture demonstrates how to read a finding; it did not analyze a recording or prove disclosure detection.

2. Inspect identity and find an existing scorecard

Supply PYAI_API_KEY privately through your server environment. Do not paste it into chat, a URL or browser code. Replace proj_your_expected_project with the project you intend to use:
The script first reads /v1/me and refuses a different project, inactive key or organization, or missing trace:read. It prints project, organization, environment and available billing/limit context before requesting Trace data. Trace reads are organization-scoped: verifying a project does not restrict the results to calls from that project. Choose only a call you are authorized to review. It then lists up to five existing scorecards using GET /v1/trace/interactions?limit=5. An empty result is not a PASS: confirm that the call used an eligible Trace path, processing finished and permissions are correct. This example does not enable monitoring or choose a call automatically.

3. Retrieve the reported evidence

Copy an authorized id returned by that list, replacing call_id_from_the_list:
This calls GET /v1/trace/interactions/{id} once after identity inspection. It rejects a mismatched ID or malformed scorecard. HTTP errors and timeouts stop the run without retries. Output files are created with private permissions and are never overwritten. Store real evidence securely; do not commit it to a public repository. Review findings[].rule_id, reason, citation, at_t and action_taken in context. A citation may identify a policy or regulation; it is not necessarily a transcript quote. A null timestamp stays null. A reported missing-disclosure finding is meaningful only for the policy and observed events that produced it. No finding does not establish that all required disclosures were checked. Check gate_health and satisfied_requirements alongside the verdict. Empty or missing health information is unknown coverage. advisory_findings remains separate from the deterministic scorecard. The script retains audit_hash but sets audit_chain_verified: false; reading a hash does not independently verify the audit chain. A reported PASS is not a legal-compliance certification.

Supported boundary and cost

This walkthrough retrieves results that already exist. The public Trace API does not offer a general analyze this transcript endpoint. The console’s uploaded-call review and the async Hear trace: true path check personal-data patterns; they do not establish consent or missing-disclosure detection. Do not substitute those paths when the user specifically requests disclosure analysis. The fictional mode uses no PyAI service. Live mode performs two bounded GET requests per run and submits no new metered speech or Trace scan. Original call processing may already have incurred usage. Enabling Trace for future eligible calls is a separate, deliberate action with current billing terms. The settings below are not prerequisites for reading an existing scorecard.

Settings and customization

Check eligible inputs before enabling processing.
Trace is in beta. Enable it deliberately for your organization; current terms and any promotional treatment are listed on the pricing page. Findings are informational and not legal advice.
You need a key with trace:configure (to manage config and rule packs) and trace:read (to read results). Add scopes in the console.

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:
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

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):
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:
Interactions, one scorecard row per call. Filter by verdict (PASS/WARN/FAIL) or agent_id:
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:
Violations, every fired rule across scorecards, for drill-down. Filter by rule_id, severity (low/medium/high/critical), or interaction_id:
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:

The console view

The Compliance / Trace tab in the console 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 and in your console.

Next steps

Trace API reference

Full request/response schemas for every /v1/trace/* endpoint.

Post-call extraction

Pull structured data out of completed calls.

Conversation intelligence

Recap: summaries and CRM sync for your calls.

Errors & limits

Error codes, pagination, and idempotency conventions.

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.