Walkthrough: review an existing sales call
Inputs: an existing Trace interaction ID and a server-side key withtrace: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
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
SupplyPYAI_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:
/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 authorizedid returned by that list, replacing call_id_from_the_list:
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 generalanalyze 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.
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: trueand belong to an organization entitled for Trace on transcription. This single-pass path cannot be combined withchannel: trueordiarize: 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 atracesummary. - Certified inbound call imports whose integration guide explicitly includes a Trace scorecard, when Trace is enabled for the organization.
Step 1, configure Trace
OnePUT sets the org-wide default; add ?agent_id= (or wrap the body as
{ "agent_id", "config" }) to override per agent:
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):"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:verdict
(PASS/WARN/FAIL) or agent_id:
call_id: findings with
reasons and cited regulations, satisfied requirements, redactions, gate health,
the verdict, and the tamper-evident audit_hash:
rule_id, severity (low/medium/high/critical), or interaction_id:
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 onetrace.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.