---
title: run operations
---

The exact fields each `run.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/reference/http-api#request) its namespace and agent; see [identities and namespaces](/concepts/identities-and-namespaces). The [operations index](/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `run.begin`

Open a RUN — one execution of a task — BEFORE you start working on it.

`POST /v1/run.begin` · MCP `loom_run_begin` · role `writer` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | required | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The conversation this run belongs to. |
| `run_id` | `str` | `''` | The run's id; empty or "-" = the server mints one. |
| `goal` | `str` | required | What the run sets out to do, in the agent's words; stored on the run row. |
| `user_request` | `str` | `''` | The original request that started the run, verbatim; empty when not given. |
| `expected_outcome` | `str` | `''` | What a successful run should produce; stored for later review, empty when not given. |
| `environment` | `str` | `''` | Free-text label of where the run executes (e.g. `ci`, `local`); stored as given. |
| `model` | `str` | `''` | The model the agent runs on; stored as given, empty when not given. |
| `consumer` | `str` | `''` | The calling integration's tag, recorded on the ledger row. |
| `role` | `str` | `''` | The agent's role in a multi-agent run — planner, executor, critic, or the team's own word. |
| `metadata` | `dict[str, Any]` | *(computed)* | Free-form key/values stored on the run; `role`, when set, is added to it. |
| `budget_usd` | `float` | `0.0` | Model spend in USD the run may reach; needs a session_id (0 = none, kept on a re-sent begin of the same run_id). |
| `budget_seconds` | `int` | `0` | Seconds the run may take (0 = none, kept on a re-sent begin of the same run_id). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `run_id` | `str` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | Always `active` for a run just opened. |
| `started_at` | `str` | When the run started, ISO UTC with a `Z`; a re-sent `run_id` keeps the first start. |
| `next` | `str` | Protocol nudge: what to do with the run_id. |

## `run.complete`

Close a run opened with run.begin — call EXACTLY ONCE when the task ends.

`POST /v1/run.complete` · MCP `loom_run_complete` · role `writer` · write · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `user_id` | `str` | `'-'` | The run's user and conversation, as run.begin took them: a token narrowed to one session resolves its scope from these, and completes only its own run. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `run_id` | `str` | required | The agent run (task scope) the call belongs to; `'-'` for none. |
| `status` | `Literal['completed', 'failed', 'cancelled']` | required | How the run ended: `completed`, `failed` or `cancelled`; also picks the default `outcome`. |
| `final_response` | `str` | `''` | The agent's final answer; stored on the run row. |
| `confidence` | `float` | `0.0` | The agent's confidence in the result (0–1), stored on the run; 0 records the session outcome label at full confidence. |
| `memories_used` | `list[str]` | *(computed)* | memory_keys the agent actually relied on (a subset of what it recalled). |
| `recalled_keys` | `list[str]` | *(computed)* | The memory keys the session's Loom tools SERVED (the plugin's PostToolUse hook stashes them from loom_search / memory.get results and hands them over at SessionEnd). |
| `outcome` | `Literal['', 'positive', 'negative', 'none']` | `''` | Outcome applied to memories_used. "" derives from status: completed → positive, failed → negative, cancelled → none. |
| `weight` | `int` | `1` | Event count each usage, evidence or harm event for `memories_used` carries (1–100). |
| `duration_ms` | `int` | `0` | Wall-clock override; 0 = computed from started_at. |
| `metadata` | `dict[str, Any]` | *(computed)* | Key/values merged into the run's stored metadata; keys given here win. |
| `reflection` | `RunReflection \| None` | `None` | Optional process learning, written as a `reflection` memory (see RunReflection). |
| `retain` | `Literal['', 'keep', 'demote', 'expire']` | `''` | What happens to the rows this run wrote. '' = the server default (settings.memory_run_complete_retain, `keep`). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `run_id` | `str` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | The status the run was closed with. |
| `duration_ms` | `int` | Run length in milliseconds: `duration_ms` from the call, else now minus `started_at`. |
| `used_applied` | `int` | memories_used keys that resolved to a live memory row (each got `used`). |
| `evidence_applied` | `int` | rows that also received a positive-outcome evidence event. |
| `harm_applied` | `int` | rows that received a negative-outcome harm event. |
| `memories_written` | `list[str]` | memory_keys written under this run_id (derived from loom.memory). |
| `recalled` | `int` | distinct memory_keys memory.search returned under this run_id — needs LOOM_SEARCH_TRACE_LOG_ENABLED; -1 when the trace log is off. |
| `observations` | `int` | episodic observations (observe.record) tagged with this run_id. |
| `procedure_runs_recorded` | `int` | procedural memories in memories_used that got a procedure.record_run row (path empty, ok = the run's outcome) — the ledger procedure.evolve reads. 0 on a `none` outcome. |
| `reflection_key` | `str` | memory_key of the reflection written from `reflection`; "" when none. |
| `retain` | `str` | Retention counts over the rows this run wrote. |
| `retained` | `int` | Rows this run wrote that the `demote`/`expire` mode left alone (pinned, verified, …); 0 under `keep`. |
| `demoted` | `int` | Rows whose confidence was lowered by `retain=demote`. |
| `expiring` | `int` | Rows given an expiry by `retain=expire`. |

## `run.get`

Replay one run: goal, status, final response, the memories it relied on, the memory_keys it wrote, how many memories it recalled and observed, and what its model turns cost.

`POST /v1/run.get` · MCP `loom_run_get` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `run_id` | `str` | required | The agent run (task scope) the call belongs to; `'-'` for none. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when no run with this id exists in the namespace; every other field is then empty. |
| `run` | `RunRow \| None` | The run row; `None` when not found. |
| `recalled` | `int` | Live derivations (not stored on the row): what the run recalled, wrote, observed and cost. |
| `recalled_keys` | `list[str]` | Keys memory.search returned under the run plus keys the hooks reported as served; empty when neither is known. |
| `memories_written` | `list[str]` | Keys written under this run's id, read live from `loom.memory`. |
| `observations` | `int` | Episodic observations (`observe.record`) tagged with this run's id. |
| `turns` | `int` | The session's turns in loom.agent_turn_usage (the plugin's Stop hook writes them) made while the run was open; 0 when the run has no session or the hook is not installed. |
| `unpriced_turns` | `int` | Those turns whose model the price table does not know: each costs 0, so `cost_usd` and a cost budget leave them out. |
| `cost_usd` | `float` | Summed model cost in USD of those turns; 0 as for `turns`. |
| `elapsed_seconds` | `int` | Seconds from started_at to completed_at (to now while active), on the server's clock; not duration_ms. |
| `over_budget` | `list[Literal['cost', 'time']]` | The budgets the run has gone past: `cost` (cost_usd > budget_usd) and `time` (elapsed_seconds > budget_seconds). |

## `run.grade`

A verdict on a CLOSED run, usually days after it — a maintainer confirmed the finding, CI passed, a reviewer rejected it.

`POST /v1/run.grade` · MCP `loom_run_grade` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `run_id` | `str` | `''` | The run to grade; "" or "-" = none. |
| `session_id` | `str` | `''` | Every closed run of this session; "" or "-" = none. |
| `grade` | `Literal['pass', 'fail']` | required | The verdict: `pass` (the result held up) or `fail`. |
| `source` | `str` | `'caller'` | Who graded: `maintainer`, `ci`, `reviewer`, `judge`… (free text, short). |
| `reason` | `str` | `''` | Why the grade was given; stored on the run as `grade_reason`. |
| `ref` | `str` | `''` | What the grade rests on: a URL, a finding key, a check run id. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `graded` | `int` | Runs whose grade was written (a closed run whose verdict changed). |
| `run_ids` | `list[str]` | Ids of the runs whose grade was written. |
| `skipped_active` | `int` | Runs of the target left alone because they are still active (not closed). |
| `unchanged` | `int` | Closed runs that already carried this grade, source, reason and ref. |
| `memories_counted` | `int` | Distinct memories the graded runs relied on (memories_used). |
| `proposals_decided` | `list[RunGradeProposal]` | Proposals the owner-set policy decided on this grade (auto mode only). |

## `run.list`

A page of a namespace's agent runs and their match count (`total`), filtered and sorted.

`POST /v1/run.list` · MCP `loom_run_list` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `''` | Only this agent's runs; "", "*" or "-" = every agent. |
| `session_id` | `str` | `''` | Only this session's runs; "", "*" or "-" = every session. |
| `status` | `Literal['', 'active', 'completed', 'failed', 'cancelled']` | `''` | Only runs in this status; "" lists every status. |
| `limit` | `int` | `50` | At most this many runs, in `order_by` order; the server caps it at 200. |
| `offset` | `int` | `0` | Runs to skip before the page (0-100,000); default 0, the first page. |
| `order_by` | `Literal['started_desc', 'started_asc', 'duration_desc', 'duration_asc', 'relied_on_desc', 'relied_on_asc']` | `'started_desc'` | Sort by start time, duration (0 while active) or memories relied on; default newest first. |
| `q` | `str` | `''` | Only runs whose goal, run id or agent holds this text, in any case; "" is no filter. |
| `memory_activity` | `Literal['', 'with', 'without']` | `''` | The Runs page folds runs that neither relied on nor wrote a memory. |
| `grade` | `Literal['', 'ungraded', 'graded', 'pass', 'fail']` | `''` | `ungraded` / `graded` / a verdict (`pass`, `fail`); "" = every run. |
| `fields` | `list[str] \| None` | `None` | The output fields the caller reads (a whitelist resolved against the row model; an unknown name is a 422); unset, every field. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `runs` | `list[RunRow]` | Matching runs in `order_by` order (newest `started_at` first by default), projected to `fields` when given. |
| `total` | `int \| None` | How many runs match the filters; null on a full page after the first. |

<!-- prettier-ignore-end -->
