> ## Documentation Index > Fetch the complete documentation index at: https://docs.komodor.com/llms.txt > Use this file to discover all available pages before exploring further. # Runs & evidence > Every execution is a run with a full evidence trail — inputs, tool calls, reasoning, output, and cost. Here is how to read it. An agent's conclusion is only as good as your ability to check it. In the Komodor Agentic Operation Platform (KAOP), every execution is a **run** that records what it was asked, everything it did, what it produced, and what it cost. This page explains what that trail contains, how to read it, and which properties of it you can actually rely on. ## The lifecycle of a run | Status | Meaning | | ----------- | ------------------------------------------------------ | | `queued` | The run exists and is waiting for a worker to claim it | | `claimed` | A worker has accepted it and is starting | | `running` | The agent is working and streaming progress | | `succeeded` | It finished and produced its output | | `failed` | It stopped with an error before producing a result | | `cancelled` | Someone stopped it deliberately | `cancelled` is kept distinct from `failed` on purpose: an operator stopping a run and an agent breaking are different facts, and metrics that conflate them mislead. Every run also records the surface that started it — `ui`, `api`, `webhook`, `cron`, `slack`, or `agent` — so you can always tell an alert-driven investigation from a manual one. See [How Run works](/manage-your-agents/run/how-it-works) for the full set of starting paths. ## What a run was asked A run's input is one JSON object, however it was supplied. From the console's run dialog you can provide it two ways: * **Prompt** — free text, submitted as `{"prompt": "…"}`, for agents driven by a natural-language instruction. * **JSON input** — an arbitrary JSON object, for agents invoked with a structured payload. JSON mode also takes an optional instruction that rides along as the `prompt` key. An agent that advertises an input schema opens in JSON mode with the editor pre-seeded from that schema and the agent's own sample values, and you can read the advertised schema in place. An agent with no schema opens in prompt mode. Either way, the stored input is the same shape, so a run started from a schedule, an endpoint, or another agent is indistinguishable in structure from one you typed. ## What a run records Evidence is streamed to the control plane by the agent's worker while the run is in progress, in batches. Nothing on this list is reconstructed afterwards — which is why it is still complete for a run that failed halfway. | Evidence | What it gives you | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Transcript** | The narration: progress notes, tool calls and their results, data pulled, drafts produced — in the order they happened | | **Trace timeline** | The structured span tree — reasoning, model calls, tool calls — with the duration of each | | **Logs** | Timestamped lines at the usual levels, for detailed diagnostics | | **Output** | The final result, in a structured channel and an optional human-readable one | | **Artifacts** | Files the run produced, openable and downloadable | | **Usage** | Model, token counts by class, and cost | | **Guardrail decisions** | Any action a policy blocked, redacted, or held for approval | | **Skills** | The skills the run actually loaded | ## Reading a run Open a run and you get its status, its input, and a set of tabs. Tabs appear only when there is something in them, so the shape of a run's page tells you something before you read a word of it. | Tab | What to look for | | ------------------ | ----------------------------------------------------------------------- | | **Run Output** | The answer. Start here, then go looking for how it got there | | **Transcript** | The readable story of the run, tool calls grouped into rounds | | **Trace Timeline** | Where the time went, call by call | | **Logs** | Detail the transcript deliberately leaves out | | **Skills** | Which runbooks and procedures were in play | | **Artifacts** | Reports and generated files, with a count | | **Guardrails** | Every policy decision that touched this run, with a count | | **Metadata** | The run's own facts — ids, thread, timings, the surface that started it | ### Output has two channels A run's output is one JSON object serving two audiences, and knowing which is which stops a lot of confusion: * **Structured output** — the top-level machine-readable fields, the substrate that automation reads: findings, counts, verdicts, flags. * **Descriptive output** — a single reserved `text` key holding human-readable markdown. The console, Slack replies, and History render it. It is a projection of the structured data for people, never a replacement for it. An automation-only agent may emit no `text` at all, and consumers then fall back to the structured payload. An agent that owes a machine-readable answer can declare its output as a schema, in which case a shape mismatch is corrected by the agent inside the same turn rather than discovered as a parse failure afterwards — and a run that produced no structured answer fails, rather than succeeding with nothing in it. ### Time breakdown A finished run shows where its wall-clock time went, by category: **Model**, **MCP tools**, **Other tools**, **Overhead**, and — only when it is non-zero — **Not measured**. The last two are the ones worth understanding, because they are different kinds of fact: * **Overhead** is the agent's own real time that no model or tool call covers — prompt assembly, framework glue, serialization, and time spent waiting on a delegated child run. For an orchestrator this is usually mostly the waiting, which is why a large number there is not automatically a problem with your code. * **Not measured** is a call that started and never reported its end. It is missing measurement, not idle time — the call may have been cut short when the run ended. It is never folded into another category and never hidden below a threshold, at any magnitude. The breakdown is computed when you read it, not stored. A run's span tree is not necessarily complete the instant the run reaches a terminal state, so anything cached would quietly miss late spans. ### What a run cost Usage counts tokens in four disjoint classes, so summing across them is honest: | Class | What it counts | | -------------------------- | --------------------------------------------------------------- | | `input_tokens` | Prompt tokens billed fresh | | `cached_input_tokens` | Prompt tokens served from the prompt cache — the cheapest class | | `cache_write_input_tokens` | Prompt tokens written into the cache — the dearest input class | | `output_tokens` | Tokens the model generated | `total_tokens` is their sum, and is derived rather than authoritative. Alongside the counts, a run records its model, provider, and cost, and whether that cost was reported by the worker or estimated. Workspace and per-agent roll-ups build on the same numbers — see [Agent spend](/manage-your-agents/optimize/agent-spend-attribution). If you read usage off the raw event stream rather than the run's recorded total: every token count on a model span is the run's **cumulative** total so far, not that turn's delta. Take the last value; never sum the series. ## When a run fails A failed run keeps its error alongside every piece of evidence collected before the failure, so the question "how far did it get?" is answerable. Runs that failed because the model provider could not serve the request — billing, credentials, rate limits — carry classified failure metadata, so the page tells you *why* it failed and who can fix it. That is deliberately distinguished from an agent that ran perfectly well and found a problem. A run can succeed and still be useless — an agent blocked by unbound tools, an unauthenticated integration, or a bad credential finishes `succeeded`. Status alone is not a quality signal; read the output. Grading output quality systematically is what [Evaluations](/manage-your-agents/optimize/evaluations) is for. ## Following a fan-out Orchestrating agents delegate, and delegation is recorded as parentage rather than inferred: * **One conversation thread** — the runs of a multi-turn exchange, oldest first. * **One run's children** — every run that this run delegated to, newest first. So an orchestrator's run page lets you walk down into each specialist it called, and each specialist's run is a first-class run with its own evidence. Where a channel reply came from an agent that delegated, the reply itself names both agents and links both runs — attribution is added by the platform, not written by the agent, so it stays correct even when the answer is not. ## Following up on a run Beneath a finished run's output sits **Continue this investigation**. From there you can ask a follow-up in KAOP chat, hand the run to a local coding agent, or — when the run saved a session snapshot — pick **Re-run the agent** to re-execute it with its tools and its earlier context, which creates a new run in the same thread. See [Chat & history](/manage-your-agents/run/chat-history) for what each destination carries. ## Why the trail is trustworthy Five properties, each of which is a design decision rather than a side effect: * **It is emitted, not inferred.** Everything you read arrived from the agent while it was working. * **Secrets never enter it.** A credential is delivered into a run in memory and is never exposed to you or written into its evidence. See [Secrets & credential handling](/security-and-governance/architecture-considerations/secrets-credential-handling). * **Policy decisions are part of the record.** An action a guardrail blocked, redacted, or held shows up on the run that attempted it — the absence of an action is evidence too. * **Runs are durable and scoped to one workspace.** Every read and write is checked against that boundary, so a run is retrievable later and only by the workspace that owns it. * **Identity is recorded from the request, not the payload.** Who started a run, and who approved or answered anything inside it, comes from the authenticated caller. See [Audit log](/security-and-governance/controls/audit-log). ## Finding runs **History** is the ledger: every run and chat session, newest first, filterable by type, status, and agent, and searchable over run and session ids, a row's title, and the agent's name or slug. The `GET /api/v1/runs` API supports the same narrowing — one agent, one conversation thread, or the children of one run — which is how you walk an orchestrator's fan-out programmatically. ## Next steps The ledger, and conversational work with the same evidence. Grade runs against explicit criteria instead of reading them one by one. Get run telemetry into your own observability stack. Have KAOP tell your systems when a run finishes. ## Related topics - [How Run works](/manage-your-agents/run/how-it-works.md) - [Build from scratch](/manage-your-agents/build/build-from-scratch.md) - [Orchestration](/manage-your-agents/run/orchestration.md) - [Integrations overview](/manage-your-agents/build/integrations-overview.md) - [Chat & history](/manage-your-agents/run/chat-history.md)