> ## 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 dashboards, widgets, and integrations > Put Trace summaries, scorecards, and completed-call events into the apps your team uses. Trace can fit into an internal operations dashboard, a CRM call panel, a customer portal, or a compliance evidence workflow. Choose the information each audience needs and keep the connection inside that audience's access controls. ## Get your first call review Open **Trace → Upload a call** to try a real call before connecting a provider. No API key or change to the organization Trace default is needed. * **Transcript:** upload a UTF-8 TXT, SRT or VTT file, or paste text, up to 200 KB. The server runs a deterministic personal data pattern review and saves its scorecard. Raw text is not retained by this transcript upload; finding citations contain redacted placeholders. Pasted text needs no transcription credits. * **Recording:** choose MP3, WAV, M4A, MP4, FLAC, OGG, WebM or AAC, up to 25 MB. Select an active project. Transcription uses workspace credits through the existing Hear path. The original recording and transcript are saved in **My work**. Accepted jobs continue after the browser closes. The worker saves the Trace scorecard before reporting completion. Open **View upload** to check progress. An owner, admin or developer can upload. People with Trace access in the workspace can review the result. Upload only calls you are allowed to process. The upload review checks email addresses, US phone numbers, payment card patterns, US social security number patterns and card security codes. These are pattern checks, not an assessment of consent, disclosures or legal compliance. Bounded English and Hindi numeric speech immediately after wording such as "phone number", "card number" or "मोबाइल नंबर" can also produce a candidate finding. These findings say **needs review**: they do not validate or repair the digits. An unusually long number labeled as a phone is shown as **Sensitive number needs review** because its data type may also be wrong. Review the recording or source. Candidate values are hidden in evidence, just like exact pattern matches. Clearly labeled order, booking and shipment references in English or Hindi are excluded per occurrence. A sensitive label in the same clause takes precedence. Other spoken numbers, other languages and transcription errors can still cause missed findings. Empty transcripts and recordings without readable speech never produce a PASS scorecard. Open the saved call review to see findings, the checks applied and the audit hash. Check whether flagged data was needed, review access and retention, and record what you decided. Full call details and audit information remain available on demand. For ongoing calls, use the setup steps below the upload option: 1. **Activate Trace** if the organization default is off. The confirmation keeps the current scoring policy. Agent overrides still apply. 2. **Connect calls.** Choose **PyAI agents** to use an agent in the workspace, or **JustCall** to connect credentials and add its completed-call webhook. Required webhook instructions appear immediately after connection. 3. **Open a review.** A real scorecard must exist before the call is marked ready. A connected provider or received webhook alone is not a completed review. **Preview an example** shows clearly labeled fictional data. Configuration, API delivery and developer options stay under advanced setup. ## Pick a starting point | Goal | Start with | Customize | | - | - | - | | Show call quality at a glance | Exposure summary | Cards, labels, order, color, theme, and spacing | | Review one call in your CRM | Interaction detail | Findings, citations, review actions, and links | | Review failed calls for an agent | Interactions list | Agent and verdict filters, pagination, assignments in your app | | Review semantic concerns | Advisory findings | Check, severity, action, and the human review process | | Send an event to your workflow | Trace Delivery | WARN/FAIL selection, destination, and signed webhook handling | | Prepare audit evidence | Summary CSV and audit templates | Reporting period, review decisions, and handoff records | The existing read APIs require `trace:read`. Configuring scoring rules requires `trace:configure`. Check the [live OpenAPI contract](https://api.pyai.com/openapi.json) before constructing an integration. A public token for a voice-agent widget does not grant access to Trace records. ## Build a summary dashboard The dashboard starter includes five cards: * **Scored calls:** the number of calls with a Trace scorecard. * **Pass rate:** PASS verdicts divided by scored calls. * **Calls with a gap:** calls with a WARN or FAIL verdict. * **Verdict mix:** PASS, WARN, and FAIL counts. * **Top rule findings:** distinct affected calls for each rule. The console builder adds presets for Operations, Risk review, and Leadership. Open **Customize layout** to choose cards, move them up or down, edit their labels, and select a 7, 30, or 90 day window. Use a light or dark theme, your brand color, and compact or comfortable spacing. A label change affects presentation, not the rules used to score calls. Save a layout in your browser for the current organization or export a layout JSON file to share with a teammate under **Layout files and saved layouts**. The layout contains display settings only. Summary CSV exports contain aggregate counts and rule IDs. Sample exports are explicitly named as samples. > [!NOTE] > > Open **Trace → More → Build & embed** in the console to design a dashboard. > The starter is available in the repository at > `examples/trace-dashboard`, with a fictional-data mode that needs no API key. > Provider-account verification for Vanta, Drata, and Secureframe is a separate > release step. An example does not establish a marketplace listing or acceptance > by an auditor. ### Keep the key on your server ```mermaid theme={null} sequenceDiagram participant Viewer as App user participant App as Your app server participant Trace as Trace API Viewer->>App: Open an authenticated dashboard App->>App: Check session and workspace permission App->>App: Resolve the authorized tenant's key App->>Trace: GET /v1/trace/exposure with trace:read Trace-->>App: Organization summary App->>App: Keep allowed aggregate fields App-->>Viewer: Private summary response ``` The starter's `server-adapter.mjs` accepts a key resolver you supply. That resolver must authenticate the user, authorize the workspace, and read the correct key from your server's secret store. Without the resolver, the adapter denies access. It does not select a tenant from browser-supplied organization IDs. Host `trace-dashboard.mjs` and `model.mjs` under your app's `/trace-widgets/` directory, and connect the server adapter to an authenticated `/api/trace-dashboard` route. Then embed: ```html theme={null} ``` The web component uses the embedding app's session and accepts a data URL on that same origin. It loads on opening, date-window changes, and manual refresh. It does not poll or include analytics. Its styles live in a Shadow DOM. Your app's content security policy must permit the component's styles. ### Use your own design system Assign an exported layout to the element's `config` property, or use `projectExposure()` from `model.mjs` with your own charts. The projection validates the counts and returns known aggregate fields. `exposureCsv()` produces a summary CSV using the same population. For a compact customer portal, choose Scored calls and Pass rate. For an internal risk review, place Calls with a gap and Top rule findings first. For a team lead, use Verdict mix and link to the private call review workflow in your app. The public exposure summary covers the whole organization across projects and environments. It does not offer an agent, project, environment, or pack filter. Do not add a filter control that leaves the underlying population unchanged. ## Add a call review panel Fetch the scorecard on your server after authorizing the requested call: ```bash theme={null} curl "https://api.pyai.com/v1/trace/interactions/$CALL_ID" \ -H "Authorization: Bearer $PYAI_API_KEY" ``` Show the verdict, rule findings, reasons, citations, and the available audit hash. Keep the call-to-customer mapping in your application. A visitor knowing a call ID does not grant permission to view its details. Raw scorecards can include call content and deserve stricter access than a summary card. You can add reviewer assignment, comments, an exception decision, and a link to a CRM case. Store those workflow states in your app or use an existing supported review surface. A Trace WARN or FAIL is not itself an unresolved ticket. ### Create an agent review queue ```bash theme={null} curl --get "https://api.pyai.com/v1/trace/interactions" \ -H "Authorization: Bearer $PYAI_API_KEY" \ --data-urlencode "agent_id=$AGENT_ID" \ --data-urlencode "verdict=FAIL" \ --data-urlencode "limit=100" ``` Follow `next_cursor` while `has_more` is true. Use the returned cursor unchanged and URL-encode it. A single page is not a total. The public list supports agent, verdict, limit, and cursor parameters; do not assume console-only search or date filters exist on the public API. ## Keep advisory review separate ```bash theme={null} curl "https://api.pyai.com/v1/trace/findings?action=escalate&limit=100" \ -H "Authorization: Bearer $PYAI_API_KEY" ``` Semantic findings arrive asynchronously and are advisory. Their reasons and confidence can help a reviewer decide what to inspect. They are separate from the scorecard verdict. Filtering by `action=escalate` selects the finding's suggested action; it does not mean that somebody has already opened a case. ## Connect Slack, tickets, and other workflows Use **Trace → More → Delivery** to configure Slack or a signed Webhook for completed scorecards. The event is `trace.scorecard.completed`. Select WARN and FAIL if your team wants to focus its feed on calls with a gap. The starter's `webhook-receiver.mjs` verifies `X-PyAI-Signature` against the raw request body, checks a five-minute timestamp tolerance, and bounds the request size. Supply a destination-specific secret and an `enqueueOnce` callback that atomically records the delivery ID and durable downstream work. It acknowledges the event only after that callback resolves. A queue failure returns an error so delivery can retry. ```mermaid theme={null} flowchart LR A[Completed scorecard] --> B[Configured destination] B --> C[Verify signature and timestamp] C --> D[Commit delivery ID and work] D --> E[Return acknowledgement] D --> F[Worker updates CRM or ticket] F --> G[Record downstream outcome] ``` Deduplicate downstream writes as well. A worker can finish a CRM write and crash before marking its local queue item complete. Keep credentials, payloads, and errors out of public pages. Unlike the summary widget, completed-call events can contain call IDs, agent IDs, and finding titles. Changing a widget's label or threshold should not silently change call routing, scoring policy, or delivery subscriptions. Make those changes in their respective configuration workflows. ## Build reports with the right denominator | Metric | Calculation | What it means | | - | - | - | | Pass rate | PASS / scored calls | Share of scored calls with a PASS verdict | | Gap rate | (WARN + FAIL) / scored calls | Share of scored calls with a gap | | Rule rate | Distinct affected calls for the rule / scored calls | Calls can appear under multiple rules | | Coverage | Scored eligible calls / all eligible calls | Needs a separate, reconciled population | When there are no scored calls, show an unavailable rate. Do not display 100% or describe the organization as having no risk. Never sum per-rule counts into a count of affected calls. Add the window and collection timestamp to snapshots saved in your warehouse. The exposure endpoint is a trailing summary, not a complete historical series. ## Extend the integration deliberately * Add your own rule packs through the supported Trace configuration API, then verify the intended behavior before enabling them for calls. * Attach a CRM case, release version, or review decision using your app's trusted call mapping. Do not include personal identifiers in a public dashboard URL. * Keep executive summaries and call investigations as separate permission levels. * Reconcile eligible calls if you need a coverage metric or audit population. * Keep provider upload acknowledgement, review acceptance, and any remediation decision as separate records in a compliance workflow. For evidence templates and worked handoff examples, see the [AI Call Agent Compliance & Audit guide](https://pyai.com/blog/ai-call-agent-compliance-audit-guide). For scoring configuration, see [Trace guardrails](/guides/trace-guardrails.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.