run operations

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

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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.