---
title: "Get an interaction (the evidence view)"
method: GET
path: "/v1/trace/interactions/{id}"
tags: ["Trace"]
---

# Get an interaction (the evidence view)

`GET /v1/trace/interactions/{id}`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/trace/interactions/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

The full per-call scorecard (findings with plain-English reasons + cited regulations, satisfied requirements, redactions, gate health, verdict) plus the tamper-evident `audit_hash`. With scorecard-v1 the response also carries the optional per-call `timeline` and `quality_metrics` eval blocks (empty until the engine emits them) and `derived_metrics`, the platform's score-ready rollup of the timeline (TTFB, turn counts, barge detect + recovery). Requires the `trace:read` scope.

## Path parameters

- `id` string, required

## Response `200`

Interaction detail

- TraceInteractionDetail
  - `object` string
  - `id` string: call_id
  - `agent_id` string, nullable
  - `product` 'hear' | 'speak' | 'clone' | 'cue' | 'omni' | 'agents' | 'null', nullable
  - `verdict` 'PASS' | 'WARN' | 'FAIL'
  - `findings` integer
  - `blocked_turns` integer
  - `modified_turns` integer
  - `packs_enforced` string
  - `scored_at` integer: Unix ms.
  - `source` string, nullable: Call origin, for example external.
  - `audit_hash` string: Hash-chain link proving this record is unaltered (the signed-evidence guarantee).
  - `scorecard` object: The full trace-scorecard-v0/v1 record: findings, satisfied requirements, redactions, gate health, verdict, and (scorecard-v1) the optional `timeline`/`quality_metrics` eval blocks.
  - `tier2_findings` TraceFinding[]: Tier-2 (async semantic) findings for this call, joined at read time. They arrive after the scorecard and never alter `audit_hash`.
    - `object` string
    - `id` string
    - `interaction_id` string: call_id
    - `agent_id` string, nullable
    - `check_id` string: minimum_necessary | brand_tone | hallucination | ambiguous_optout | context_pii | …
    - `severity` 'low' | 'medium' | 'high' | 'critical'
    - `verdict` string
    - `confidence` number: Model confidence, 0..1.
    - `action` 'flag' | 'preempt_next' | 'escalate': What the finding asks for; never blocks the current turn.
    - `speaker` 'agent' | 'caller' | 'any' | 'null', nullable
    - `reason` string: Plain-English explanation.
    - `preempt_instruction` string, nullable: Constraint applied to the NEXT turn when action is preempt_next.
    - `at_t` number, nullable: Seconds since call start.
    - `tier` integer
  - `timeline` TraceTimelineEvent[]: scorecard-v1 per-call timeline (transcript turns + latency stamps used for eval scoring), hoisted from the scorecard for convenience. Empty `[]` until the engine emits it.
    - `seq` integer: Turn sequence number within the call.
    - `t_ms` number: Offset from call start, in milliseconds.
    - `role` string: Who spoke this turn, e.g. `agent` | `caller`.
    - `text` string: Transcript for the turn.
    - `ttfb_ms` number: Time-to-first-audio for the turn (latency scoring).
    - `endpointing_ms` number: Turn-detection (endpointing) latency.
    - `barge` object: Barge-in (caller interrupts the agent) detect latency + recovery for the turn.
      - `detect_ms` number: Time to detect the barge-in.
      - `recovered` boolean: Whether the agent recovered gracefully.
    - `tool_calls` object[]: Tool/function calls the agent made during the turn (tool-use scoring).
      - `name` string
      - `args` unknown
      - `result` unknown
      - `t_ms` number: Offset from call start, in milliseconds.
  - `quality_metrics` TraceQualityMetrics: scorecard-v1 per-call rolled-up quality metrics. All optional + inert until the engine emits them.
    - `wer` number: Word error rate (0..1).
    - `ttfb_ms` number: Time-to-first-audio for the call, in milliseconds.
    - `turn_p95_ms` number: p95 end-to-end turn latency, in milliseconds.
    - `barge_recovery` number: Barge-in recovery rate (0..1).
    - `task_success` number: Task-success rate (0..1).
    - `vaqi` number: Voice-agent quality index.
  - `derived_metrics` TraceDerivedCallMetrics: Read-time per-call eval aggregates derived from the scorecard-v1 timeline (ServiceAgent feedback §13c / PYAI_EVALS_PLATFORM_PLAN Layer B). Pure and inert (zero counts, `null` percentiles) until the engine emits a timeline.
    - `turns` integer: Total timeline turns.
    - `turns_by_role` object: Turn count per role (e.g. `agent` / `caller`).
    - `ttfb_ms` TraceLatencySummary: Distribution of one latency sample set (ms). Percentiles are `null` when there are no samples.
      - `count` integer: Number of samples.
      - `p50` number, nullable: Median (ms).
      - `p95` number, nullable: p95 (ms).
      - `p99` number, nullable: p99 (ms).
    - `endpointing_ms` TraceLatencySummary: Distribution of one latency sample set (ms). Percentiles are `null` when there are no samples.
      - `count` integer: Number of samples.
      - `p50` number, nullable: Median (ms).
      - `p95` number, nullable: p95 (ms).
      - `p99` number, nullable: p99 (ms).
    - `barge` object: Barge-in (caller interrupts the agent) counts + detect-latency distribution.
      - `count` integer: Barge-in events detected.
      - `recovered` integer: Barge-ins the agent recovered from.
      - `recovery_rate` number, nullable: recovered / count (0..1); `null` when there were no barge-ins.
      - `detect_ms` TraceLatencySummary: Distribution of one latency sample set (ms). Percentiles are `null` when there are no samples.
        - `count` integer: Number of samples.
        - `p50` number, nullable: Median (ms).
        - `p95` number, nullable: p95 (ms).
        - `p99` number, nullable: p99 (ms).
    - `tool_calls` integer: Total tool/function calls across all turns.

## Other responses

- `404`: No such interaction for this tenant.

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)