# Investigate agent runs

> Triage AI executions by customer, status, cost, tools, and quality evidence.

Canonical page: https://anectico.com/docs/investigate/agent-runs/


Open **Agents → Agent Runs** to investigate an AI workflow as one execution rather than a collection
of unrelated model spans.

## Find the run that matters

Filter by immutable agent observation identity, customer or distinct ID, terminal status, any
provider used by the run, and quality state. The Fleet page fills the agent identity for you and
shows the agent name only as its label, so two agents with the same name remain separate. Sort by
duration, steps, tool calls, or cost to find outliers. The summary cards cover every run matching the current
filters, not only the visible page; use the page controls below the table to move through the full
result set. A run without a customer link means no step of the run recorded an identity.

A customer filter selects whole runs, not individual steps. A run matches when **any** of its steps
carries that identity — an assistant typically records the customer once, on the request that starts
the run, and not again on each model call or tool call beneath it — and the run's steps, tool calls,
tokens and cost always cover **every** step of that run, whether or not the step itself carried the
identity. The same run therefore shows the same totals here and on the customer timeline.

Time and environment filters also select whole runs. If a step matches the requested window and
environment, Anectico includes the complete run: an earlier root still supplies the real start,
agent release and terminal declaration, and every child still contributes to tokens and cost. A
long-running execution therefore has the same rollup in the list and its detail view.

Opening an individual run keeps the active agent, person and account selectors in the URL. The run
itself is addressed by its exact recorded trace id; its span ids, parent ids and causal link trace/
span ids are carried as recorded rather than derived from labels or neighboring spans.

The run identity prefers the recorded agent name. For a direct model call without an agent name,
Anectico shows the model instead; if neither is present, it falls back to the root operation. The root
operation remains visible separately so an HTTP or job span is not mistaken for an agent name.

Every declared terminal state is one of **Completed**, **Failed**, **Timed out**, **Cancelled**, or
**Max steps**; runs without trustworthy terminal evidence show **Undeclared**. The detail and
customer timeline also explain the safe terminal reason code. An
explicit outcome on the earliest agent-invocation span is authoritative, so a failed child tool does
not turn an explicitly cancelled or max-steps run into a failure. A status attached to another kind
of step, or a value outside the five states above, is not treated as a run declaration. Supported
frameworks whose own agent root declares a successful or failed span outcome are interpreted from
that exact root; otherwise the run remains visibly **Undeclared** and child errors stay available as
step evidence. A run can use multiple model providers, so Anectico displays the complete sorted
provider set and the provider filter matches when any step used that provider.

Open a run and review:

- the execution sequence and slow or failed steps;
- repeated model or tool calls;
- token use and calculated cost;
- errors and status transitions;
- human feedback and automatic evaluation results; and
- connected customer, trace, replay, or Issue evidence.

## Interpret quality scores carefully

Human feedback captures reviewer judgment. Automatic scores apply the project's configured evaluator
and sampling rule. Neither explains a failure by itself; compare the cited run steps, tool outputs,
and application evidence.

The two are stored separately and shown separately, on purpose. An automatic score names the exact
evaluator version that produced it and can be reproduced later, which is what a release gate reads. A
person's judgment cannot be reproduced and is never read as evidence — keeping them apart is what
makes "the reviewer said 0.2 and the judge said 0.9" a question you can ask at all.

Agent-run reads are project-scoped. The CLI sends the active project selected by `--project`,
`ANECTICO_PROJECT`, or the current profile; an organization-level credential must select one, while a
project-scoped API key can rely on its signed project binding. With MCP, an organization-level
credential must provide `project_id`; a project-scoped credential can omit it because Anectico pins the
call to the project signed into the key. Passing a sibling project cannot widen that key. Missing,
foreign-project, and random run IDs return the same not-found response, while list calls for foreign
or random projects both return an empty result.

Feedback belongs to the same project as its run. Anectico records the reviewer from your session; you
cannot submit feedback as somebody else, and there is no field to try.

Each reviewer has one judgment per project, run, and metric name. Safe retries return that same
judgment instead of creating duplicates. Submitting changed feedback for the same identity edits it in
place: the creation time stays stable while the update time advances. Different reviewers and metrics
remain separate judgments, and a person's judgment never merges with an automatic one.

A number is optional. Leaving one off records a label alone — a thumbs-up is a judgment, not a score
of 1.0, and a thumbs-down is not a score of 0.

The feedback controls are shown only with `scores:write` — a permission every member holds — and a
refreshed viewer permission removes them immediately; the server independently enforces the same
permission. Reading feedback back needs `scores:read`.

They stay available on a run whose **transcript** you are not allowed to read. Rating a run and
reading what it said are separate capabilities: a project whose content policy closes transcript
reads still shows the run's shape, its scores and the judgments already recorded, and a member with
`scores:write` can still record one. Withholding the transcript withholds what the run said, not
your ability to judge it.

If a run was not sampled, that is not a passing score. If an evaluation lacks the inputs needed for a
criterion, change the recorded evidence or criterion before increasing the sample rate. See
[Quality evaluations](/docs/agents/quality-evaluations) for evaluators, sampling rules and budgets.

## Move from run to impact

Open the customer to see what preceded and followed the run. Compare similar runs for other customers
before treating one expensive or failed execution as systemic. Use **Customer Detective** when a
grounded cross-signal explanation is more useful than manually reading every span: a run
investigation follows the run's own trace outward to the Issues it produced, the log lines and
service metrics recorded around it, and the customer session it was served in, and cites each one.
When reproduction matters, ask that run's investigation to **replay this run**. The result identifies
the recorded run and sandbox plan, reports whether the recorded sequence reproduced exactly, and
names effectful calls the sandbox stubbed. Replay follows only recorded steps; it does not generate
alternative scenarios. One replay attempt is available per investigation, and any permission,
content-setting, budget, or availability refusal is included in the answer instead of being silently
omitted.
See [what an agent-run investigation examines](/docs/investigate/customer-detective).

- [Record LLM calls](/docs/instrument/llm-calls)
- [Explain LLM spend per customer](/docs/investigate/llm-spend)
- [Review usage and AI settings](/docs/manage/usage-and-ai-settings)
- [How a session, turn, and run relate](/docs/reference/rest-api#what-happened-in-a-conversation)
- [How complete is my agent telemetry?](/docs/reference/rest-api#how-complete-is-my-agent-telemetry)