cost operations

The exact fields each cost.* 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.

cost.agent_summary

The coding agent's own spend (loom.agent_turn_usage) over a date window — the series cost.summary does not cover, which prices what LOOM spends upstream.

POST /v1/cost.agent_summary · MCP loom_cost_agent_summary · role viewer · read

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str \| None	None	The namespace the op reads or writes.
from_date	date	required	Inclusive lower bound of the window, compared against each turn's UTC day.
to_date	date	required	Inclusive upper bound
group_by	list[Literal['namespace', 'agent', 'day', 'model', 'consumer', 'session_id']]	['model']	Dimensions to GROUP BY.
agent	str \| None	None	The writing or reading agent; '-' or '*' means any agent where the op allows it.
consumer	str \| None	None	The calling integration's tag, recorded on the ledger row.

Output field	Type	Meaning
rows	list[CostAgentSummaryRow]	One row per distinct value of the group_by dimensions, highest cost first, at most 5,000; empty when the caller can read no namespace in the org.
total_turns	int	Sum of turns over the returned rows.
total_sessions	int	Distinct sessions: the sum over rows when grouped by session_id, else the largest row's count (a lower bound when a session spans several rows).
total_cost_usd	float	Sum of cost_usd over the returned rows, in USD; unpriced turns count as 0.
unpriced_turns	int	Turns whose model the price table did not know, summed over the returned rows.

cost.budget_status

This namespace's upstream spend in the last 24 h against its cap.

POST /v1/cost.budget_status · MCP loom_cost_budget_status · role viewer · read

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str \| None	None	The namespace the op reads or writes.

Output field	Type	Meaning
namespace	str	The namespace the op reads or writes.
spent_24h_usd	float	Upstream spend over the last 24 hours (rolling, not calendar day), in USD.
cap_usd	float	Effective cap: per-namespace override if set, else global default. 0.0 means uncapped; org-wide rollups are always uncapped.
cap_source	Literal['namespace', 'global', 'uncapped', 'org']	Where cap_usd came from: namespace (its own cap), global (the server default), uncapped (neither is set) or org (an org-wide rollup, which has no cap).
over_cap	bool	True when a cap is set and spent_24h_usd has reached it; always false org-wide.
pct_of_cap	float \| None	0..1, None when uncapped
namespaces_with_spend	int	org-wide mode only

cost.record_turns

The coding agent's own spend for one session, a batch of turns per call.

POST /v1/cost.record_turns · MCP loom_cost_record_turns · role writer · idempotent · 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	'-'	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	required	The session or conversation the row belongs to; '-' for none.
consumer	str	''	The calling integration's tag, recorded on the ledger row.
turns	list[TurnUsage]	required	The turns to record, 1 to 200 per call; a turn re-sent with the same message_id replaces its earlier row.

Output field	Type	Meaning
recorded	int	Turns written to the ledger; 0 when the write failed (the call still succeeds).
priced	int	Turns whose model the price table knows; 0 when the write failed.
unpriced_models	list[str]	Models the price table does not know: their rows carry cost_usd=0 and priced=false; add them to PRICE_PER_1K_TOKENS rather than trusting $0.
cost_usd	float	Total price of the priced turns in this batch, in USD, rounded to 6 places.
turns_dated_ahead	int	Turns dated over 5 s after the server's clock: the client's clock runs ahead, so a run's cost window may place them late.

cost.summary

Cost rollup over a date window.

POST /v1/cost.summary · MCP loom_cost_summary · 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 \| None	None	The namespace the op reads or writes.
from_date	date	required	Inclusive lower bound of the window, compared against each event's UTC day.
to_date	date	required	Inclusive upper bound
group_by	list[Literal['namespace', 'agent', 'day', 'operation', 'memory_key', 'user_id', 'model', 'traffic_class', 'instance_label', 'build_commit']]	(computed)	Dimensions to GROUP BY.
agent	str \| None	None	The writing or reading agent; '-' or '*' means any agent where the op allows it.
operation	str \| None	None	Only this op name (for example 'memory.ask'); None counts every op.
user_id	str \| None	None	One end user only (forces an events scan); None or "-" = every user.
traffic_class	str \| None	None	One class only (production | interactive | bench); forces an events scan like user_id.
instance_label	str \| None	None	One launcher's processes (deploy:web:blue, iso:w6m1:7864, …); forces an events scan like user_id.
include_cache	bool	True	Read the exact-prompt response cache's totals off the ledger (out_llm_cache_hits / out_llm_cache_saved_usd on memory.ask rows).

Output field	Type	Meaning
rows	list[CostSummaryRow]	One row per distinct value of the group_by dimensions, most ops first, at most 5,000; empty when the caller can read no namespace in the org.
total_ops	int	Sum of ops over the returned rows.
total_errors	int	Sum of errors (ops that failed) over the returned rows.
total_cost_usd	float	Sum of the upstream provider spend (upstream_cost_usd) over the returned rows, in USD.
cache_hits	int	Exact-prompt response cache over the window — LLM calls served from the table and the price-table dollars they did not spend.
cache_saved_usd	float	USD the response-cache hits did not spend, rounded to 6 places; 0 when include_cache is off or the filter excludes memory.ask.