Investigate agent runs

An agent run is one AI workflow, read as one execution. It is not a collection of unrelated model spans. Your agent finds the run that matters and reads its steps. You open the run page it links to and check the run yourself.

Person filters include only identifiers Anectico resolved. Unmapped declarations stay in unfiltered event, conversation, turn and cost totals. An unresolved person reference keeps the application’s distinct_id and leaves person_id empty; it does not name a person. Counts are as reliable as your application's customer identification: intake telemetry does not authenticate each end user.

Ask your agent

List the agent runs that failed in production in the last day, with their cost. For the most expensive one, show me the steps, the repeated tool calls, and the customer. Give me a link.

Job	MCP tool or action	CLI command
List runs, newest first, with outcome, steps, tools, providers, cost, and release coverage	list_agent_runs	anectico agent-runs list
Read one run: status, steps, tokens, cost, and a bounded transcript	get_agent_run	anectico agent-runs get
Read a run’s complete execution graph	get_agent_run_graph (a read action)	anectico agent-runs graph
Read the context events of a run	list_context_events (a read action)	anectico agent-runs context
Read conversations and their turns	list_agent_sessions, list_agent_turns, get_agent_session	anectico agent-sessions list, anectico agent-sessions turns, anectico agent-sessions get
Check how complete the agent telemetry is	get_telemetry_completeness (a read action)	anectico agent-runs completeness
List the agents and their 24-hour run health	list_agent_fleet	anectico fleet list
Record a human judgment of a run	submit_annotation (a write action)	anectico evals annotations add
Read the judgments recorded for runs	list_eval_annotations (a read action)	anectico evals annotations list

list_agent_runs, the conversation tools, and the graph tools need agents:read. get_agent_run needs agents:content:read, because it can return the conversation transcript. Recording a judgment needs scores:write, and reading judgments needs scores:read. MCP calls also need mcp:read or mcp:write.

What your agent gets back

list_agent_runs filters by agent, person, account, environment, release, terminal status, provider, free text, and a relative or exact window. Each row has its own url. A run without a customer link means that no step of the run recorded an identity. get_agent_run and get_agent_run_graph return the run’s link as well.

Omitting the MCP run-list window reads the last 24 hours. MCP returns the resolved absolute start_time and end_time; use those exact values when continuing with a cursor so the window stays fixed. A malformed relative since is refused, including zero, negative and overflowing ages.

Run detail reads return at most the earliest 1,000 spans by start time. MCP get_agent_run extracts messages from those spans, then keeps the first two and last four available messages with each body capped. Check partial, returned_span_count, and total_span_count: when the span read is partial, the envelope has status: partial and the whole-run transcript is unknown. Its selected tail may precede the actual ending. transcript_available counts messages found in the returned span prefix; transcript_count counts the shown messages. transcript_total is present only when the span read is complete. The run header’s separately aggregated steps, tokens, cost and declared outcome still cover the complete selected run. REST and anectico agent-runs get retain the same span completeness fields. There is no detail cursor for the omitted spans.

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

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, the agent release, and the terminal declaration, and every child still contributes to tokens and cost. A long-running execution therefore has the same rollup in the list and in its detail view.

The run is addressed by its exact recorded trace id. Its span ids, parent ids, and causal link trace and span ids are carried as recorded. They are not derived from labels or neighboring spans.

For REST searches, GET /api/v1/agent-runs?q=... matches a case-insensitive literal substring within any one of seven run fields: run ID, agent name, root operation, service name, conversation ID, recorded distinct ID, or model. Text cannot match across two fields. Spaces and characters such as %, _, and backslashes are literal, not wildcards. Release, canonical person ID, and providers are not searched by q. Use their dedicated filters instead. Search selects complete runs, and it also applies to the release-coverage counts that are returned with the list.

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 stays 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 the person 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 stays visibly Undeclared, and child errors stay available as step evidence. A run can use multiple model providers, so Anectico gives the complete sorted provider set, and the provider filter matches when any step used that provider.

Open the proof

Open the link from the result. It opens the run page at /view/agent-run/:runId, with project_id in the address. The page is read-only. It names its project, and its one action is Copy link. See Proof pages. On the page, review:

• the execution sequence and the 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, the tool outputs, and the application evidence.

The two are stored separately and shown separately, on purpose. An automatic score names the exact evaluator version that produced it, and it 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. 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 credential. 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 stay 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.

Past feedback shows each judgment’s metric name, recorded label, number when supplied, and comment. A recorded zero is 0. A label-only judgment has no number. Only thumbs_up and thumbs_down labels show their corresponding thumb on the run page. Custom labels such as bad or needs_review are shown as written, without inferring approval from the label or number.

Recording feedback needs scores:write, a permission every member holds. The server enforces it independently. Reading feedback back needs scores: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. It does not remove your ability to judge it.

If a run was not sampled, that is not a passing score. If an evaluation lacks the inputs it needs for a criterion, change the recorded evidence or the criterion before you increase the sample rate. See Quality evaluations for evaluators, sampling rules, and budgets.

Move from run to impact

Open the customer’s person page to see what preceded and followed the run. Compare similar runs for other customers before you treat one expensive or failed execution as systemic. Ask the agent to follow the run outward: the Issues it produced (list_issues), the log lines and service metrics recorded around it (search_logs, get_service_health), and the customer session it was served in (get_session_signals). The run’s own trace is the place to start (get_trace).

• Record LLM calls
• Explain LLM spend per customer
• Review usage, model prices and decision scoring
• How a session, turn, and run relate
• How complete is my agent telemetry?