Skip to content
ClickHouse Loom
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.
user_id str | None None Named end user’s rolling-24h budget within namespace; omitted returns namespace totals.
Output field Type Meaning
namespace str The namespace the op reads or writes.
user_id str | None The selected logical end user, or None for namespace and org totals.
spent_24h_usd float | None Rolling 24h upstream spend in USD; user mode returns null unless the caller is a platform admin without namespace-role restrictions.
cap_usd float Effective namespace or named-user cap: namespace override, else server default. 0.0 means uncapped; org-wide rollups are always uncapped.
cap_source Literal['namespace', 'global', 'namespace_user', 'global_user', 'uncapped', 'org'] namespace / global for namespace caps, namespace_user / global_user for user caps, uncapped when disabled, or org for an org-wide rollup.
over_cap bool True when real spend reaches the selected cap, even if withheld; false org-wide.
namespace_over_cap bool | None In user mode, namespace spend can independently prevent new work.
pct_of_cap float | None Fraction spent, clamped to 0..1; null when uncapped or user spend is withheld.
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.

Was this page helpful?