---
title: "List Tier-2 semantic findings"
method: GET
path: "/v1/trace/findings"
tags: ["Trace"]
---

# List Tier-2 semantic findings

`GET /v1/trace/findings`

## Request

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

Cursor-paginated Tier-2 (async semantic) findings, the model-judged concerns deterministic rules can't catch (HIPAA minimum-necessary, brand tone, hallucination-vs-knowledge-base, indirect opt-out, context-dependent PII). These are advisory and non-blocking, and are kept separate from the hash-chained Tier-0 violations. Filter by `check_id`, `action`, `severity`, or `interaction_id`. The CCO alerts feed is `action=escalate` and/or `severity=critical`. Requires the `trace:read` scope.

## Query parameters

- `check_id` string
- `action` 'flag' | 'preempt_next' | 'escalate'
- `severity` 'low' | 'medium' | 'high' | 'critical'
- `interaction_id` string
- `limit` integer
- `cursor` string

## Response `200`

Findings

- object
  - `object` string
  - `data` TraceFinding[]
    - `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
  - `has_more` boolean
  - `next_cursor` string, nullable

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)

---

[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/819d8e7c4d09?raw)