Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

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.

Operaciones de cost

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.