As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Operações de cost
Os campos exatos que cada operação cost.* recebe e retorna.
Toda op é POST /v1/<op> via HTTP e a ferramenta MCP loom_<op>. Os campos de identidade (org, namespace, agent, user_id, session_id) são preenchidos a partir do token e da sessão MCP quando o transporte consegue; em uma chamada HTTP sem token em um servidor de usuário único, é usada a org da instalação em todas as ops, exceto code.* e tracker.* (que mantêm a org do seu plano), e em algumas ops também o namespace e o agente; veja identidades e namespaces. O índice de operações explica role, kind e a listagem all do MCP. Campos de entrada desconhecidos são atendidos e nomeados em ignored_args.
cost.agent_summary
O gasto do próprio agente de código (loom.agent_turn_usage) em uma janela de datas — a série que cost.summary não cobre, pois ele precifica o que o LOOM gasta upstream.
POST /v1/cost.agent_summary · MCP loom_cost_agent_summary · role viewer · leitura
| Campo de entrada | Tipo | Padrão | Significado |
|---|---|---|---|
org |
str |
obrigatório | O tenant (primeiro elemento da tupla de identidade). |
namespace |
str \| None |
None |
O namespace que a op lê ou escreve. |
from_date |
date |
obrigatório | Limite inferior inclusivo da janela, comparado com o dia UTC de cada turno. |
to_date |
date |
obrigatório | Limite superior inclusivo |
group_by |
list[Literal['namespace', 'agent', 'day', 'model', 'consumer', 'session_id']] |
['model'] |
Dimensões para o GROUP BY. |
agent |
str \| None |
None |
O agente que escreve ou lê; '-' ou '*' significa qualquer agente, quando a op permite. |
consumer |
str \| None |
None |
A tag da integração que faz a chamada, registrada na linha do ledger. |
| Campo de saída | Tipo | Significado |
|---|---|---|
rows |
list[CostAgentSummaryRow] |
Uma linha para cada valor distinto das dimensões de group_by, do maior custo para o menor, no máximo 5,000; vazio quando o chamador não pode ler nenhum namespace da org. |
total_turns |
int |
Soma de turns nas linhas retornadas. |
total_sessions |
int |
Sessões distintas: a soma das linhas quando agrupado por session_id; caso contrário, a contagem da maior linha (um limite inferior quando uma sessão abrange várias linhas). |
total_cost_usd |
float |
Soma de cost_usd nas linhas retornadas, em USD; turnos sem preço contam como 0. |
unpriced_turns |
int |
Turnos cujo modelo a tabela de preços não conhecia, somados nas linhas retornadas. |
cost.budget_status
O gasto upstream deste namespace nas últimas 24 h em relação ao seu limite.
POST /v1/cost.budget_status · MCP loom_cost_budget_status · role viewer · leitura
| Campo de entrada | Tipo | Padrão | Significado |
|---|---|---|---|
org |
str |
obrigatório | O tenant (primeiro elemento da tupla de identidade). |
namespace |
str \| None |
None |
O namespace que a op lê ou grava. |
user_id |
str \| None |
None |
Orçamento móvel de 24 h do usuário final nomeado dentro do namespace; se omitido, retorna os totais do namespace. |
| Campo de saída | Tipo | Significado |
|---|---|---|
namespace |
str |
O namespace que a op lê ou grava. |
user_id |
str \| None |
O usuário final lógico selecionado, ou None para os totais do namespace e da org. |
spent_24h_usd |
float \| None |
Gasto upstream móvel de 24 h em USD; no modo de usuário, retorna null, a menos que quem chama seja um administrador da plataforma sem restrições de role de namespace. |
cap_usd |
float |
Limite efetivo do namespace ou do usuário nomeado: a substituição do namespace, senão o padrão do servidor. 0.0 significa sem limite; os consolidados de toda a org nunca têm limite. |
cap_source |
Literal['namespace', 'global', 'namespace_user', 'global_user', 'uncapped', 'org'] |
namespace / global para limites de namespace, namespace_user / global_user para limites de usuário, uncapped quando desativado, ou org para um consolidado de toda a org. |
over_cap |
bool |
True quando o gasto real atinge o limite selecionado, mesmo que oculto; false no modo de toda a org. |
namespace_over_cap |
bool \| None |
No modo de usuário, o gasto do namespace pode, de forma independente, impedir novas tarefas. |
pct_of_cap |
float \| None |
Fração gasta, limitada ao intervalo de 0 a 1; null quando não há limite ou o gasto do usuário está oculto. |
namespaces_with_spend |
int |
somente no modo de toda a org |
cost.record_turns
O gasto do próprio agente de código em uma sessão, com um lote de turnos por chamada.
POST /v1/cost.record_turns · MCP loom_cost_record_turns · role writer · idempotente · não listado no toolset all do MCP
| Campo de entrada | Tipo | Padrão | Significado |
|---|---|---|---|
org |
str |
obrigatório | O tenant (primeiro elemento da tupla de identidade). |
namespace |
str |
obrigatório | O namespace que a op lê ou grava. |
agent |
str |
'-' |
O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permite. |
user_id |
str |
'-' |
O usuário final a quem a linha pertence; '-' para nenhum. |
session_id |
str |
obrigatório | A sessão ou conversa a que a linha pertence; '-' para nenhuma. |
consumer |
str |
'' |
A tag da integração que fez a chamada, registrada na linha do ledger. |
turns |
list[TurnUsage] |
obrigatório | Os turnos a registrar, de 1 a 200 por chamada; um turno reenviado com o mesmo message_id substitui a linha anterior. |
| Campo de saída | Tipo | Significado |
|---|---|---|
recorded |
int |
Turnos gravados no ledger; 0 quando a gravação falhou (a chamada ainda assim é bem-sucedida). |
priced |
int |
Turnos cujo modelo consta na tabela de preços; 0 quando a gravação falhou. |
unpriced_models |
list[str] |
Modelos que a tabela de preços não conhece: suas linhas têm cost_usd=0 e priced=false; adicione-os a PRICE_PER_1K_TOKENS em vez de confiar em $0. |
cost_usd |
float |
Preço total dos turnos com preço neste lote, em USD, arredondado a 6 casas. |
turns_dated_ahead |
int |
Turnos datados mais de 5 s à frente do relógio do servidor: o relógio do cliente está adiantado, então a janela de custo de uma execução pode posicioná-los tarde demais. |
cost.summary
Consolidação de custos em um intervalo de datas.
POST /v1/cost.summary · MCP loom_cost_summary · role viewer · leitura · não listado no toolset all do MCP
| Campo de entrada | Tipo | Padrão | Significado |
|---|---|---|---|
org |
str |
obrigatório | O tenant (primeiro elemento da tupla de identidade). |
namespace |
str \| None |
None |
O namespace que a op lê ou escreve. |
from_date |
date |
obrigatório | Limite inferior inclusivo do intervalo, comparado com o dia UTC de cada evento. |
to_date |
date |
obrigatório | Limite superior inclusivo |
group_by |
list[Literal['namespace', 'agent', 'day', 'operation', 'memory_key', 'user_id', 'model', 'traffic_class', 'instance_label', 'build_commit']] |
(calculado) | Dimensões para o GROUP BY. |
agent |
str \| None |
None |
O agente que escreve ou lê; '-' ou '*' significa qualquer agente, onde a op permitir. |
operation |
str \| None |
None |
Somente este nome de op (por exemplo 'memory.ask'); None conta todas as ops. |
user_id |
str \| None |
None |
Somente um usuário final (força uma varredura de events); None ou "-" = todos os usuários. |
traffic_class |
str \| None |
None |
Somente uma classe (production | interactive | bench); força uma varredura de events, como user_id. |
instance_label |
str \| None |
None |
Os processos de um único launcher (deploy:web:blue, iso:w6m1:7864, …); força uma varredura de events, como user_id. |
include_cache |
bool |
True |
Lê do ledger os totais do cache de respostas por prompt exato (out_llm_cache_hits / out_llm_cache_saved_usd nas linhas de memory.ask). |
| Campo de saída | Tipo | Significado |
|---|---|---|
rows |
list[CostSummaryRow] |
Uma linha para cada valor distinto das dimensões de group_by, com as ops mais frequentes primeiro, no máximo 5,000; vazio quando o chamador não pode ler nenhum namespace na org. |
total_ops |
int |
Soma de ops nas linhas retornadas. |
total_errors |
int |
Soma de errors (ops que falharam) nas linhas retornadas. |
total_cost_usd |
float |
Soma do gasto com o provedor upstream (upstream_cost_usd) nas linhas retornadas, em USD. |
cache_hits |
int |
Cache de respostas por prompt exato no intervalo — chamadas de LLM atendidas pela tabela e os dólares da tabela de preços que não foram gastos. |
cache_saved_usd |
float |
USD que os acertos do cache de respostas deixaram de gastar, arredondado para 6 casas; 0 quando include_cache está desligado ou o filtro exclui memory.ask. |