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

# Metrics

> Design campaign metrics that help agents make good research decisions.

Each research campaign declares one primary metric. In normal agent-first usage,
the Onyx orchestrator chooses the first version from your `/onyx` prompt, records
it in `onyx/setup.json` and `onyx/onyx.md`, and validates the setup workflow
before hypothesis workers start Research.

## Metric Fields

| Field     | Meaning                                                            |
| --------- | ------------------------------------------------------------------ |
| Name      | The metric key emitted by the workflow step marked `metric: true`. |
| Unit      | Optional display unit, such as `ms`, `points`, or `percent`.       |
| Direction | `maximize` or `minimize`.                                          |

Example:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
/onyx Reduce controller latency, minimize latency_ms in milliseconds
```

If the first metric choice is wrong, ask the orchestrator to revise setup and
validate again before starting or continuing hypothesis workers.

## Metric Output

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
METRIC latency_ms=14.2
```

The metric step must emit exactly one line for the primary metric. Secondary
metrics are out of scope for workflow v1; use guardrail steps and notes for
tradeoffs until a future schema introduces explicit secondary metrics.

## Status and Best Results

Common statuses:

* `succeeded`: the workflow passed and the primary metric was parsed.
* `failed`: a required non-guardrail command failed or did not emit the primary metric.
* `checks_failed`: a required guardrail failed after a valid metric.
* `setup_violation`: the result changed protected setup paths or out-of-scope files.
* `accepted` or `rejected`: manually classified outcomes.

Best-so-far should only build from valid results that satisfy the campaign goal and correctness constraints.