<a id="cost-operations"></a>

# Operaciones de `cost`

<!-- i18n: source=docs/reference/operations/cost.md blob=f8bcf1fd1aead97faf00f604f2c42a7dca73bcda model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/cost.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/cost.md), which is authoritative.


Los campos exactos que recibe y devuelve cada operación `cost.*`.

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

Cada op es `POST /v1/<op>` sobre HTTP y la herramienta MCP `loom_<op>`. Los campos de identidad (`org`, `namespace`, `agent`, `user_id`, `session_id`) se completan a partir del token y de la sesión MCP cuando el transporte puede hacerlo; en una llamada HTTP sin token en un servidor de un solo usuario, se usa la org de la instalación en todas las ops excepto `code.*` y `tracker.*` (que conservan la de su plano), y en [algunas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) también su espacio de nombres y su agente; consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md). El [índice de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica el rol, el tipo (kind) y el listado `all` de MCP. Los campos de entrada desconocidos se atienden y se nombran en `ignored_args`.

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

<a id="costagent_summary"></a>

## `cost.agent_summary`

El gasto propio del agente de código (loom.agent_turn_usage) en una ventana de fechas: la serie que `cost.summary` no cubre, ya que esta calcula el costo de lo que LOOM gasta upstream.

`POST /v1/cost.agent_summary` · MCP `loom_cost_agent_summary` · rol `viewer` · lectura

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str \| None` | `None` | El espacio de nombres que la op lee o escribe. |
| `from_date` | `date` | obligatorio | Límite inferior inclusivo de la ventana, comparado con el día UTC de cada turno. |
| `to_date` | `date` | obligatorio | Límite superior inclusivo |
| `group_by` | `list[Literal['namespace', 'agent', 'day', 'model', 'consumer', 'session_id']]` | `['model']` | Dimensiones por las que se aplica GROUP BY. |
| `agent` | `str \| None` | `None` | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. |
| `consumer` | `str \| None` | `None` | La etiqueta de la integración que llama, registrada en la fila del ledger. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[CostAgentSummaryRow]` | Una fila por cada valor distinto de las dimensiones de `group_by`, de mayor a menor costo, con un máximo de 5,000; vacío cuando el llamador no puede leer ningún espacio de nombres de la org. |
| `total_turns` | `int` | Suma de `turns` sobre las filas devueltas. |
| `total_sessions` | `int` | Sesiones distintas: la suma de las filas cuando se agrupa por `session_id`; en caso contrario, el conteo de la fila más grande (una cota inferior cuando una sesión abarca varias filas). |
| `total_cost_usd` | `float` | Suma de `cost_usd` sobre las filas devueltas, en USD; los turnos sin precio cuentan como 0. |
| `unpriced_turns` | `int` | Turnos cuyo modelo la tabla de precios no conocía, sumados sobre las filas devueltas. |

<a id="costbudget_status"></a>

## `cost.budget_status`

Gasto upstream de este espacio de nombres en las últimas 24 h frente a su límite.

`POST /v1/cost.budget_status` · MCP `loom_cost_budget_status` · rol `viewer` · lectura

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str \| None` | `None` | El espacio de nombres que la operación lee o escribe. |
| `user_id` | `str \| None` | `None` | Presupuesto móvil de 24 h del usuario final indicado dentro del espacio de nombres; si se omite, devuelve los totales del espacio de nombres. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `namespace` | `str` | El espacio de nombres que la operación lee o escribe. |
| `user_id` | `str \| None` | El usuario final lógico seleccionado, o None para los totales del espacio de nombres y de la organización. |
| `spent_24h_usd` | `float \| None` | Gasto upstream móvil de 24 h en USD; el modo de usuario devuelve null a menos que quien llama sea un administrador de la plataforma sin restricciones de rol en el espacio de nombres. |
| `cap_usd` | `float` | Límite efectivo del espacio de nombres o del usuario indicado: la sobrescritura del espacio de nombres o, en su defecto, el valor por defecto del servidor. 0.0 significa sin límite; los agregados de toda la organización nunca tienen límite. |
| `cap_source` | `Literal['namespace', 'global', 'namespace_user', 'global_user', 'uncapped', 'org']` | `namespace` / `global` para los límites del espacio de nombres, `namespace_user` / `global_user` para los límites de usuario, `uncapped` cuando está desactivado, u `org` para un agregado de toda la organización. |
| `over_cap` | `bool` | True cuando el gasto real alcanza el límite seleccionado, aunque se oculte; false en el modo de toda la organización. |
| `namespace_over_cap` | `bool \| None` | En el modo de usuario, el gasto del espacio de nombres puede impedir por sí solo nuevo trabajo. |
| `pct_of_cap` | `float \| None` | Fracción gastada, limitada al rango 0..1; null cuando no hay límite o se oculta el gasto del usuario. |
| `namespaces_with_spend` | `int` | solo en el modo de toda la organización |

<a id="costrecord_turns"></a>

## `cost.record_turns`

El gasto propio del agente de programación en una sesión, un lote de turnos por llamada.

`POST /v1/cost.record_turns` · MCP `loom_cost_record_turns` · rol `writer` · idempotente · no figura en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. |
| `agent` | `str` | `'-'` | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. |
| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si ninguno. |
| `session_id` | `str` | obligatorio | La sesión o conversación a la que pertenece la fila; `'-'` si ninguna. |
| `consumer` | `str` | `''` | La etiqueta de la integración que llama, registrada en la fila del libro de costes. |
| `turns` | `list[TurnUsage]` | obligatorio | Los turnos que se van a registrar, de 1 a 200 por llamada; un turno reenviado con el mismo `message_id` reemplaza su fila anterior. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `recorded` | `int` | Turnos escritos en el libro de costes; 0 cuando la escritura falló (la llamada igualmente tiene éxito). |
| `priced` | `int` | Turnos cuyo modelo conoce la tabla de precios; 0 cuando la escritura falló. |
| `unpriced_models` | `list[str]` | Modelos que la tabla de precios no conoce: sus filas llevan cost_usd=0 y priced=false; agréguelos a PRICE_PER_1K_TOKENS en lugar de confiar en $0. |
| `cost_usd` | `float` | Precio total de los turnos con precio en este lote, en USD, redondeado a 6 decimales. |
| `turns_dated_ahead` | `int` | Turnos con fecha más de 5 s posterior al reloj del servidor: el reloj del cliente va adelantado, por lo que la ventana de costes de una ejecución puede situarlos más tarde. |

<a id="costsummary"></a>

## `cost.summary`

Resumen de costos en una ventana de fechas.

`POST /v1/cost.summary` · MCP `loom_cost_summary` · rol `viewer` · lectura · no figura en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str \| None` | `None` | El espacio de nombres que la op lee o escribe. |
| `from_date` | `date` | obligatorio | Límite inferior inclusivo de la ventana, comparado con el día UTC de cada evento. |
| `to_date` | `date` | obligatorio | Límite superior inclusivo |
| `group_by` | `list[Literal['namespace', 'agent', 'day', 'operation', 'memory_key', 'user_id', 'model', 'traffic_class', 'instance_label', 'build_commit']]` | *(calculado)* | Dimensiones por las que se hace GROUP BY. |
| `agent` | `str \| None` | `None` | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. |
| `operation` | `str \| None` | `None` | Solo este nombre de op (por ejemplo 'memory.ask'); None cuenta todas las ops. |
| `user_id` | `str \| None` | `None` | Un solo usuario final (fuerza un escaneo de events); None o "-" = todos los usuarios. |
| `traffic_class` | `str \| None` | `None` | Solo una clase (production \| interactive \| bench); fuerza un escaneo de events igual que `user_id`. |
| `instance_label` | `str \| None` | `None` | Los procesos de un lanzador (`deploy:web:blue`, `iso:w6m1:7864`, …); fuerza un escaneo de events igual que `user_id`. |
| `include_cache` | `bool` | `True` | Lee del ledger los totales de la caché de respuestas por prompt exacto (`out_llm_cache_hits` / `out_llm_cache_saved_usd` en las filas de memory.ask). |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[CostSummaryRow]` | Una fila por cada valor distinto de las dimensiones de `group_by`, con más ops primero, hasta 5,000; vacío cuando el llamador no puede leer ningún espacio de nombres de la org. |
| `total_ops` | `int` | Suma de `ops` en las filas devueltas. |
| `total_errors` | `int` | Suma de `errors` (ops que fallaron) en las filas devueltas. |
| `total_cost_usd` | `float` | Suma del gasto del proveedor upstream (`upstream_cost_usd`) en las filas devueltas, en USD. |
| `cache_hits` | `int` | Caché de respuestas por prompt exacto durante la ventana: llamadas al LLM servidas desde la tabla y los dólares de la tabla de precios que no se gastaron. |
| `cache_saved_usd` | `float` | USD que los aciertos de la caché de respuestas no gastaron, redondeados a 6 decimales; 0 cuando `include_cache` está desactivado o el filtro excluye `memory.ask`. |

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