A finding is a structured, org-level issue that groups one or more
conversations exhibiting the same problem — a recurring script failure, a
mispronounced product name, a tool the agent keeps misusing. It is a curated
record, created by a person or surfaced by AI, with its own title,
description, priority, assignee, tags, and a set of linked calls.
Don’t confuse a finding with the per-call analysis_findings produced during
conversation analysis. Those are observations on a
single call. A finding sits one level up: it is the durable, shareable issue
you actually triage and fix, and it draws its evidence from the calls you
link to it.
Anatomy of a finding
| Field | What it is |
|---|
| Title | Short headline for the issue. |
| Description | Rich text (Tiptap / ProseMirror JSON) — context, repro notes, links. |
| Agents | Derived automatically from the linked conversations; a finding can span several agents. |
| Category | One of the finding types, or none. |
| Tags | Free-form strings for your own grouping and filtering. |
| Status | open / acknowledged / resolved / ignored. See Status. |
| Priority | none / low / medium / high / urgent. |
| Calls count | Number of conversations linked to the finding. |
| Volume | Share of the agent’s calls in the snapshot window that this finding covers. |
| Assignee | The org member who owns the finding (optional). |
| Discovered | Timestamp of the earliest linked call. |
| Last seen | Timestamp of the most recent linked call. |
null when there were no agent calls in
the window to compare against.
Status
| Status | Meaning | When to use |
|---|
| Open | Active issue still being worked. | Default for a new finding. |
| Acknowledged | Seen and accepted; a fix is still pending. | You’ve triaged it and confirmed it’s real, but haven’t addressed it yet. |
| Resolved | Fixed or addressed. | The underlying problem is handled. |
| Ignored | Noted but not actionable. | Won’t-fix, expected behavior, or out of scope. |
The status is ignored, not “dismissed”. Open, acknowledged, resolved, and
ignored are the only four values.
Priority
Five levels, from lowest to highest: none, low, medium, high,
urgent. Priority is independent of status — an open finding can be any
priority, and you set it when triaging.
Categories
A finding’s category is one of these seven types (or left empty):
- Voicemail not detected
- Bad pronunciation
- Does not follow script
- Bad ASR
- Does not understand the user
- Does not use tooling correctly
- Inconsistent voice
Linking conversations
Calls attach to a finding through the finding_conversations join. Linking is
idempotent — adding a conversation that’s already linked returns the
existing link rather than creating a duplicate. A conversation must belong to
the same org as the finding, so you can’t accidentally pull in another
tenant’s call.
The reverse view holds too: a conversation’s detail page lists every finding
it’s linked to, so you can jump from a single call to the broader issue it’s
an example of.
Each linked call carries its own comments, and a comment can be anchored to a
slice of the transcript with annotationStartMs and annotationEndMs. That
lets you point at the exact moment a call went wrong — “the agent talked over
the caller from 0:42 to 0:51” — instead of describing it in prose. Every
comment records its author and a type (a plain comment or a transcript
annotation).
Working a finding
From the finding detail page you can:
- Set priority, assignee, and status. The status button in the
top-right advances a finding to its next stage in one click (an open finding
→ Acknowledge, an acknowledged one → Resolve), with a dropdown for the
other transitions.
- Edit the title and the rich description. The description editor
supports headings, lists, diagrams,
@-mentions, and call examples —
type /call to embed one of the finding’s linked calls. The embed plays the
recording (with the annotated moments marked on the scrub bar) and shows the
annotated transcript excerpt inline, so the writeup points straight at the
moment that proves the issue.
- Copy a finding prompt — a packaged summary (title, category, status,
description, agents, linked calls) you can hand to an LLM for a deeper look
or a draft fix.
- Push to Linear if your org has it connected, turning the finding into a
tracked issue. See Linear.
Linked solutions can also surface on a finding to track the fix
alongside the problem.
Programmatic access
Findings are fully scriptable over the REST API:
| Method & path | Does |
|---|
GET /v1/findings | List findings (filter by status, priority, tags). |
POST /v1/findings | Create a finding. |
GET /v1/findings/{id} | Fetch one finding. |
PATCH /v1/findings/{id} | Update title, description, status, priority, tags, type, assignee. |
GET /v1/findings/{id}/conversations | List linked conversations. |
POST /v1/findings/{id}/conversations | Attach a conversation (idempotent). |
DELETE /v1/findings/{id}/conversations/{conversationId} | Detach a conversation. |
GET .../conversations/{conversationId}/comments | List comments and annotations on a link. |
POST .../conversations/{conversationId}/comments | Add a comment or annotation. |
list_findings,
get_finding, create_finding, update_finding,
add_conversation_to_finding, and annotate_finding_conversation — so an
agent can triage findings directly.
- Conversations — the calls and transcripts a finding links to.
- Solutions — the agent-scoped fix that addresses a finding.
- Linear — push findings into your issue tracker.
- REST API · MCP — triage findings programmatically.
