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

# Operações de `cost`

<!-- i18n: source=docs/reference/operations/cost.md blob=f8bcf1fd1aead97faf00f604f2c42a7dca73bcda model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em 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.


Os campos exatos que cada operação `cost.*` recebe e retorna.

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

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](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) também o namespace e o agente; veja [identidades e namespaces](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e nomeados em `ignored_args`.

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

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

## `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. |

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

## `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 |

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

## `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. |

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

## `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`. |

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