Pular para o conteúdo
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Operações de cost

Operações de cost

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.

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.

Esta página foi útil?