Skip to main content
GET
/
v1
/
trace
/
interactions
/
{id}
Get an interaction (the evidence view)
curl --request GET \
  --url https://api.pyai.com/v1/trace/interactions/{id} \
  --header 'Authorization: Bearer <token>'
{
  "object": "trace.interaction",
  "id": "<string>",
  "agent_id": "<string>",
  "findings": 123,
  "blocked_turns": 123,
  "modified_turns": 123,
  "packs_enforced": "<string>",
  "scored_at": 123,
  "audit_hash": "<string>",
  "scorecard": {},
  "tier2_findings": [
    {
      "object": "trace.finding",
      "id": "<string>",
      "interaction_id": "<string>",
      "agent_id": "<string>",
      "check_id": "hallucination",
      "verdict": "concern",
      "confidence": 123,
      "reason": "<string>",
      "preempt_instruction": "<string>",
      "at_t": 123,
      "tier": 2
    }
  ],
  "timeline": [
    {
      "seq": 123,
      "t_ms": 123,
      "role": "<string>",
      "text": "<string>",
      "ttfb_ms": 123,
      "endpointing_ms": 123,
      "barge": {
        "detect_ms": 123,
        "recovered": true
      },
      "tool_calls": [
        {
          "name": "<string>",
          "args": "<unknown>",
          "result": "<unknown>",
          "t_ms": 123
        }
      ]
    }
  ],
  "quality_metrics": {
    "wer": 123,
    "ttfb_ms": 123,
    "turn_p95_ms": 123,
    "barge_recovery": 123,
    "task_success": 123,
    "vaqi": 123
  },
  "derived_metrics": {
    "turns": 123,
    "turns_by_role": {},
    "ttfb_ms": {
      "count": 123,
      "p50": 123,
      "p95": 123,
      "p99": 123
    },
    "endpointing_ms": {
      "count": 123,
      "p50": 123,
      "p95": 123,
      "p99": 123
    },
    "barge": {
      "count": 123,
      "recovered": 123,
      "recovery_rate": 123,
      "detect_ms": {
        "count": 123,
        "p50": 123,
        "p95": 123,
        "p99": 123
      }
    },
    "tool_calls": 123
  }
}

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Path Parameters

id
string
required

The call_id.

Response

Interaction detail

object
string
Example:

"trace.interaction"

id
string

call_id

agent_id
string | null
product
enum<string> | null
Available options:
hear,
voice,
speak,
clone,
cue,
flow,
omni,
agents,
null
verdict
enum<string>
Available options:
PASS,
WARN,
FAIL
findings
integer
blocked_turns
integer
modified_turns
integer
packs_enforced
string
scored_at
integer

Unix ms.

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
object[]

Tier-2 (async semantic) findings for this call, joined at read time. They arrive after the scorecard and never alter audit_hash.

timeline
object[]

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.

quality_metrics
object

scorecard-v1 per-call rolled-up quality metrics, hoisted from the scorecard. null until the engine emits it.

derived_metrics
object

Platform-computed rollup of the timeline into score-ready eval aggregates (TTFB, turn counts, barge detect + recovery). Always present; zero counts and null percentiles until the engine emits a timeline. Percentiles use the same method as the offline eval harness, so an online per-call score lines up with the offline benchmark.