> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Findings

> Structured issues across your conversations — status, priority, linked calls, and inline annotations.

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](/docs/conversations). 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](#categories), or none.                                       |
| **Tags**        | Free-form strings for your own grouping and filtering.                                  |
| **Status**      | `open` / `acknowledged` / `resolved` / `ignored`. See [Status](#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.                                               |

**Volume** is snapshotted when the finding is created: the numerator is the
linked conversations inside the analyzed window, and the denominator is *all*
conversations for the same agents over that same window. Later platform-wide
uploads don't auto-link to existing findings, so they can't dilute the
percentage after the fact. Volume is `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.                           |

<Note>
  The status is `ignored`, not "dismissed". Open, acknowledged, resolved, and
  ignored are the only four values.
</Note>

## 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.

## Annotations and comments

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](/docs/integrations/linear).

Linked [solutions](/docs/solutions) can also surface on a finding to track the fix
alongside the problem.

## Programmatic access

Findings are fully scriptable over the [REST API](/api-reference/agents/list-agents):

| 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.                                       |

The same operations are exposed as [MCP](/docs/mcp) tools — `list_findings`,
`get_finding`, `create_finding`, `update_finding`,
`add_conversation_to_finding`, and `annotate_finding_conversation` — so an
agent can triage findings directly.

## Related

* [Conversations](/docs/conversations) — the calls and transcripts a finding links to.
* [Solutions](/docs/solutions) — the agent-scoped fix that addresses a finding.
* [Linear](/docs/integrations/linear) — push findings into your issue tracker.
* [REST API](/api-reference/agents/list-agents) · [MCP](/docs/mcp) — triage findings programmatically.