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

# Observability Overview

> What Verial captures during a rollout, and how to read it back.

Every benchmark rollout produces a stack of structured evidence. The agent drives sandbox endpoints (FHIR, HL7, voice, fax, portal, SFTP, X12); Verial records every observable interaction; the [verification engine](/guides/concepts/verification) scores that recorded state into per-criterion results. Observability in Verial means reading that stack back after the run.

## The Feedback Loop

```mermaid theme={null}
graph LR
  BR["Benchmark Run<br/>(verdict, score)"]:::step --> TR["Task Run<br/>(verdict, score, axes)"]:::step
  TR --> CR["Criterion Run<br/>(passed, score, details)"]:::step
  CR --> EV["Evidence<br/>(field results, transcripts, paths)"]:::step
  EV --> SE["Sandbox Events<br/>(raw interactions)"]:::step

  classDef step fill:#2563eb,color:#fff,stroke:#1d4ed8
```

You can traverse that loop top-down from any completed run: start at the aggregate verdict, drill into task verdicts and per-axis scores, open a failing criterion run to see its evidence payload, and drop down to raw sandbox events when you need the exact request or transcript turn.

## What You Can Inspect Today

* **Aggregate scores and verdicts** on a [Benchmark Run](/api-reference/resources/runs) (`score`, `verdict`, list of task runs).
* **Per-task scoring** on a [Task Run](/api-reference/resources/task-runs): `verdict`, `score`, `axes` (correctness, safety, efficiency, or whatever axes the benchmark declares), and a `criterion_runs` array.
* **Per-criterion results and evidence** on a [Criterion Run](/api-reference/resources/criterion-runs): `passed`, `score`, `details`, and a structured `evidence` payload whose shape depends on the check type.
* **Raw sandbox events** via `GET /sandboxes/{id}/events`: the lowest-level record of FHIR calls, HL7 messages, portal actions, SFTP uploads, voice turns, fax documents, and X12 responses captured during the rollout.

The [Run Results](/guides/observability/run-results) page walks through reading a completed run top-down. The [Interactions](/guides/observability/interactions) page covers the raw evidence per protocol.

<Note>
  Dashboards, real-time monitoring, trace search, and anomaly detection are
  planned but not yet available. Today, observability in Verial means inspecting
  completed runs and their recorded evidence through the API.
</Note>

## Where Evidence Lives

| Layer                                          | Where it lives    | Read with                     |
| ---------------------------------------------- | ----------------- | ----------------------------- |
| Run-level score and verdict                    | Benchmark Run row | `GET /v1/benchmark-runs/{id}` |
| Task-level score, verdict, axes                | Task Run row      | `GET /task-runs/{id}`         |
| Per-criterion pass/score + structured evidence | Criterion Run row | `GET /criterion-runs/{id}`    |
| Raw protocol interactions                      | Sandbox event log | `GET /sandboxes/{id}/events`  |

Criterion Run evidence is always available via `GET /criterion-runs/{id}`, including for runs created with `scored: true` (where the task-run completion response elides details and field-level evidence to avoid leaking the rubric to the agent).

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Results" icon="list-check" href="/guides/observability/run-results">
    Read a completed benchmark run top-down: verdict, axes, criteria, evidence.
  </Card>

  <Card title="Interactions" icon="magnifying-glass" href="/guides/observability/interactions">
    Inspect raw recorded evidence per protocol (FHIR, HL7, voice, fax, portal, SFTP, X12).
  </Card>
</CardGroup>