---
title: cost operations
---

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

## `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`. |

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