Usage e orçamentos

Todos os endpoints de usage exigem from e to em ISO datetime.

GET /v1/usage/summary?from=2026-06-01T00:00:00.000Z&to=2026-06-23T23:59:59.000Z&projectId=proj_...

Filtros disponíveis:

Um budget é um teto por meter e cadência, com uma ação: alert só mede; block barra novas execuções. GET /v1/usage/budgets devolve os tetos do workspace confrontados com o uso do período mensal corrente (UTC). Os tetos são configurados pela Noorden.

const { period, data } = await client.usage.budgets();

{
  "period": {
    "start": "2026-08-01T00:00:00.000Z",
    "end": "2026-09-01T00:00:00.000Z",
    "label": "2026-08"
  },
  "data": [
    {
      "agentId": null,
      "agentName": null,
      "meter": "cost_brl",
      "limit": 5000,
      "used": 4210.35,
      "remaining": 789.65,
      "ratio": 0.842,
      "exceeded": false,
      "action": "block",
      "cadence": "P1M"
    }
  ]
}

ratio é used / limit e não é limitado a 1 — acima de 1 significa estouro.

Um budget tem duas dimensões possíveis. agentId ausente (null na resposta) é o teto do workspace — o envelope. agentId presente é o teto daquele agent dentro do envelope. Os dois convivem no mesmo conjunto; a chave de unicidade é (escopo, meter, cadência), então um teto de cost_brl no workspace não colide com um teto de cost_brl num agent.

Meters aceitos por escopo de agent: apenas cost_brl e tokens. São os meters derivados do consumo de tokens, a única fonte que carrega a dimensão de agent. Um teto de agent sobre qualquer outro meter nunca encontraria consumo — seria um teto inerte —, e por isso é recusado na escrita.

As duas dimensões valem, e basta uma estourar para barrar — o mais restritivo ganha por construção, sem comparar limites (os meters podem nem ser os mesmos). Com as duas estouradas, a resposta aponta o workspace: enquanto o envelope estiver estourado, nenhum agent roda, e apontar o agent mandaria você para uma correção que não destravaria nada.

Com action: "block" e o teto estourado, as escritas que iniciam consumo respondem 403:

{
  "error": {
    "code": "budget.exceeded",
    "message": "Limite de consumo do agente excedido — fale com a Noorden",
    "requestId": "req_...",
    "details": { "scope": "agent", "meter": "cost_brl", "limit": 500, "used": 512.4 }
  }
}

O code é budget.exceeded nos dois escopos — quem já trata o 403 do workspace não quebra porque o limite agora pode ser de um agent. O que muda é o details, que aqui é contrato público: scope (workspace ou agent), meter, limit e used. Leia scope se o seu backend precisa reagir diferente: subir o teto do agent não destrava nada enquanto o envelope do workspace estiver estourado.

Os gates cobrem os caminhos que criam execução: criação de session, criação de experimento de agent, inbound de canal (WhatsApp e webchat), abertura de conversa, handoff para um agent e disparo de automation. Na automation o bloqueio não vira 403 — não há chamador esperando: o run é gravado com status: "error" e o motivo budget_exceeded.