Operaciones de `cost`
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Los campos exactos que recibe y devuelve cada operación cost.*.
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 también su espacio de nombres y su agente; consulta identidades y espacios de nombres. El índice de operaciones 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.
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. |
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 |
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. |
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. |