Orçamentos

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. Os Budgets (orçamentos) aplicam controles de gastos a um alvo nomeado. Cada orçamento define um escopo (a que ele se aplica), limites por período (quanto pode ser gasto ou consumido em cada período de redefinição) e uma data de expiração opcional, após a qual o orçamento deixa de ser aplicado. Quando um limite de custo ou de tokens é atingido, as solicitações que correspondem ao escopo do orçamento são bloqueadas até que o período seja redefinido. Os limites de solicitações por minuto bloqueiam por apenas um minuto, independentemente do período de redefinição. Vários orçamentos em níveis diferentes podem se aplicar à mesma solicitação ao mesmo tempo, e cada um é aplicado de forma independente; consulte Níveis de orçamento e interação. Casos de uso comuns:

Limite o gasto mensal por cliente ou tenant definindo o escopo de um orçamento para uma Identity.
Evite que um ambiente de staging ou de CI consuma créditos de produção definindo o escopo de um orçamento para a respectiva API Key.
Limite a exposição a um provedor ou modelo caro durante a avaliação definindo o escopo de um orçamento para um Provider ou Model.
Aplique um teto de custo para todo o workspace como rede de segurança definindo o escopo de um orçamento para o Workspace. O uso é contabilizado após a conclusão de cada solicitação, portanto solicitações em andamento no momento em que um limite é atingido ainda podem ser concluídas.
Controle os gastos de um experimento com prazo definido usando um período de redefinição One-time com data de expiração.

Acesse Settings > Organization > Budgets para gerenciar os orçamentos.

No console, apenas membros Admin podem criar, editar ou excluir orçamentos. Consulte Membros e equipes para conhecer as funções. Pela API, os orçamentos são gerenciados com uma Management Key que tenha a permissão Budgets; chaves de API restritas a um projeto não podem gerenciar orçamentos.

Visão geral

A tabela Budgets lista todos os orçamentos da organização.

Coluna	Descrição
Budget	O nome que identifica o orçamento.
Scope	O tipo de entidade à qual o orçamento se aplica: Workspace, Project, Identity, API Key, Provider ou Model.
Target	A própria entidade, como o workspace, o nome de um projeto, o nome de uma chave de API, o nome de uma identidade, um provedor ou o nome de um modelo.
Limits	Os limites de custo e de tokens configurados para o período de redefinição. Clique na linha de um orçamento para ver o uso atual.
Reset	O período de redefinição configurado: Daily, Weekly, Monthly, Yearly ou One-time (sem redefinição automática).
Expires	Tempo restante até o orçamento deixar de ser aplicado. É exibido em vermelho quando a expiração se aproxima. Após a expiração, o orçamento permanece na lista, mas deixa de ser aplicado. Fica em branco se o orçamento nunca expira.
Updated	A data da última modificação do orçamento.

Use Filter para restringir a lista por Period (Daily, Monthly, One-time, Weekly, Yearly), Scope ou Status (Active, Expired). Use Sort by para reordenar por Expiry soon, Newest ou Recently updated.

Monitorar o uso

Clique na linha de um orçamento para abrir a página de detalhes:

Um card de métrica para cada limite configurado (Total spend, Tokens, Req per minute) mostra o uso atual, uma barra de progresso e a porcentagem consumida.
Scope, o período de Resets, a contagem regressiva de Renews in e a data de Expires aparecem na parte superior.

Clique em Adjust limits para editar os limites por período ou a data de expiração do orçamento.
Clique em Add threshold na seção Alerts para configurar um alerta.
Clique em Delete Budget para removê-lo permanentemente. A aplicação é interrompida imediatamente.

Criar um orçamento

Abra a caixa de diálogo de criação

Clique em Budget no canto superior direito da página Budgets.

Defina o escopo

Em Scope, selecione a que o orçamento se aplica em Applies to:

Opção	Descrição
Workspace	Aplica-se ao workspace inteiro.
Project	Aplica-se a um projeto específico.
Identity	Aplica-se a um contato pelo ID externo.
API Key	Aplica-se a uma chave de API específica.
Provider	Aplica-se a todas as solicitações a um provedor. Corresponde ao segmento do provedor na referência do modelo (`openai` em `openai/gpt-5.6-sol`).
Model	Aplica-se a um modelo específico, identificado pela referência completa do modelo conforme enviada na solicitação (`openai/gpt-5.6-sol`).

Para todos os tipos de escopo, exceto Workspace, aparece um segundo campo para selecionar o alvo específico (por exemplo, qual chave de API ou qual identidade).

É permitido apenas um orçamento por alvo. Se já existir um orçamento para o alvo selecionado, um erro é exibido no próprio formulário e o orçamento não pode ser criado até que outro alvo seja selecionado.

Consulte Níveis de orçamento e interação para entender como orçamentos em níveis diferentes se aplicam à mesma solicitação.

Configure os limites por período

Em Period limits, defina o Reset period (obrigatório) e um ou mais dos seguintes limites:

Limite	Unidade	Descrição
Cost	USD	Gasto máximo permitido por período de redefinição.
Tokens limit	K Tokens	Teto de tokens por período de redefinição, em milhares. A API recebe tokens inteiros em `limits.token_limit`.
Requests per minute	Req/min	Teto de taxa aplicado a cada minuto, o tempo todo.

Deixe um limite em 0 para mantê-lo sem configuração. Pelo menos um limite precisa ter um valor diferente de zero para criar o orçamento.Os períodos de redefinição seguem um cronograma fixo:

Período	Redefine em
Daily	Meia-noite UTC
Weekly	Segunda-feira, meia-noite UTC
Monthly	Dia 1º do mês, meia-noite UTC
Yearly	1º de janeiro, meia-noite UTC
One-time	Não é redefinido. O limite se aplica durante toda a vigência do orçamento.

Requests per minute é uma janela fixa de 60 segundos que começa com a primeira solicitação, independentemente do período de redefinição. Consulte Limites de orçamento.

Se um orçamento se esgotar antes da redefinição do período, um administrador pode aumentar o limite para liberar o uso imediatamente. O uso existente não é removido; o limite maior apenas permite que a entidade consuma mais dentro do período atual.

Defina uma data de expiração (opcional)

Em Expiration, defina uma Expiration date se o orçamento precisar deixar de ser aplicado após uma data específica. Mantenha Never expires para um orçamento por tempo indeterminado.

Crie o orçamento

Clique em Create budget. O orçamento aparece na lista imediatamente e passa a ser aplicado a partir da próxima solicitação.

Editar ou excluir um orçamento

Selecione o menu em qualquer linha de orçamento para:

Edit: atualizar os limites por período ou a data de expiração. O escopo e o alvo não podem ser alterados após a criação.
Delete: remover o orçamento permanentemente. A aplicação é interrompida imediatamente.

Os orçamentos também podem ser gerenciados programaticamente com uma Management Key:

Chaves de API comuns não podem gerenciar orçamentos.

Configurar alertas

Os Alerts avisam os notificadores configurados quando o uso de custo de um orçamento ultrapassa um limite percentual. O gateway realiza duas verificações separadas:

Antes de uma solicitação começar, o gateway verifica se o orçamento não foi totalmente consumido. As solicitações são bloqueadas quando o uso chega a 100%.
Após a conclusão de cada solicitação, ele avalia os limites de alerta com base no uso atualizado, portanto uma notificação pode chegar com um pequeno atraso em relação ao momento em que o limite foi ultrapassado.

Cada alerta é disparado no máximo uma vez por período e é reativado na redefinição ou em uma alteração de limite. Exemplo: um limite de custo de 80% no orçamento de um projeto, que notifica o administrador do projeto por e-mail, dá tempo para reagir antes que o orçamento bloqueie o tráfego em 100%.

Um alerta de orçamento é disparado em uma porcentagem de um limite.

Os alertas acompanham apenas a dimensão de custo (BUDGET_ALERT_DIMENSION_COST), portanto é necessário definir um limite de custo antes que Add threshold fique disponível.
Um alerta BUDGET_ALERT_DIMENSION_TOKENS é rejeitado.
Limites de solicitações por minuto não disparam alertas.

Para alertas sobre latência, erros ou resultados de guardrails, consulte a página Alerts do AI Studio.

Criar um notificador

Os Notifiers (notificadores) precisam existir antes de serem vinculados a um alerta. Crie um em Settings → Organization → Notifiers, no próprio formulário do alerta ou com a Notifiers API. Consulte Notificadores para conhecer os canais, os campos de destino e o passo a passo no AI Studio.

Criar um alerta

A seção Alerts fica no painel de criação/edição do orçamento e na página de detalhes dele (abra um orçamento clicando na linha correspondente na lista Budgets).

Adicione um limite

Na seção Alerts, clique em Add threshold.

Defina a porcentagem do limite

Insira um número inteiro entre 1 e 100. Cada orçamento permite apenas um alerta por porcentagem de limite; limites duplicados são rejeitados.

Adicione notificadores

Clique em Add notifiers e pesquise um ou mais notificadores já criados para receber o alerta. É necessário pelo menos um notificador. Cada alerta permite no máximo 10 notificadores.

Salve o alerta

Clique em Add alert (ou em Save changes ao editar um alerta existente).

Os alertas existentes aparecem como linhas na seção Alerts. Selecione para editar um limite ou seus notificadores, ou para excluir o alerta.

Exemplos

Enviar notificações para um canal do Microsoft Teams

Encaminhe notificações de alerta para um canal do Microsoft Teams com um notificador de webhook genérico. O Teams renderiza as mensagens em seu próprio formato de card, por isso o webhook aponta para um pequeno relay que converte o payload de notificação do Toqan Router antes de encaminhá-lo ao canal.

Crie o webhook de entrada do Teams

No canal de destino do Microsoft Teams, abra Workflows (ou Power Automate), pesquise o modelo Post to a channel when a webhook request is received, conclua a configuração e copie a URL de webhook gerada.

Implante um relay de payload

O Toqan Router envia o envelope de notificação bruto como JSON, e o Teams aceita apenas seu próprio formato de message card, então o webhook não pode apontar diretamente para a URL do Teams. Implante um pequeno relay que converta o payload:

Código do relay

JavaScript

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    let envelope;
    try {
      envelope = await request.json();
    } catch {
      return new Response("Invalid JSON body", { status: 400 });
    }
    const links = envelope.links ?? [];

    const card = {
      "@type": "MessageCard",
      "@context": "http://schema.org/extensions",
      themeColor: severityColor(envelope.severity),
      title: envelope.title,
      text: envelope.body,
      sections: [
        {
          facts: [
            { name: "Severity", value: envelope.severity },
            ...links.map((link) => ({ name: link.text, value: link.url })),
          ],
        },
      ],
    };

    const teamsResponse = await fetch(env.TEAMS_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(card),
    });

    if (!teamsResponse.ok) {
      // Relay the status so Toqan Router retries the delivery.
      console.log(`Teams rejected the message: ${teamsResponse.status}`);
      return new Response(`Teams rejected the message: ${teamsResponse.status}`, {
        status: teamsResponse.status,
      });
    }

    console.log(`Forwarded notification ${envelope.id} to Teams (${teamsResponse.status})`);
    return new Response("OK", { status: 200 });
  },
};

function severityColor(severity) {
  switch (severity) {
    case "critical":
      return "B71C1C";
    case "warning":
      return "F57C00";
    case "ok":
      return "2E7D32";
    default:
      return "1565C0";
  }
}

Defina TEAMS_WEBHOOK_URL com a URL de webhook da etapa anterior. O exemplo é implantado como um Cloudflare Worker; qualquer endpoint HTTP que aceite JSON funciona.

Crie o notificador de webhook

Em Settings → Organization → Notifiers, clique em Notifier, insira um Name, selecione Webhook como canal em Send via e cole a URL do relay em Webhook URL. Cabeçalhos de solicitação personalizados são opcionais.Para criar o notificador pela API:

curl --location 'https://router.toqan.ai/eu/v2/notifiers' \
--header "Authorization: Bearer $TOQAN_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_name": "Teams alerts",
    "type": "NOTIFIER_TYPE_WEBHOOK",
    "webhook_url": "https://teams-relay.example.workers.dev"
}'

Consulte a referência da API para a especificação completa dos parâmetros.

Vincule o notificador a um alerta

Adicione o notificador a um alerta de orçamento em Add notifiers ou a um alerta de Observability em Notify via. Cada alerta aceita até 10 notificadores.

Teste a entrega

Crie um orçamento com um limite de custo baixo e um alerta com um limite baixo e, em seguida, faça uma solicitação que o ultrapasse. O alerta é disparado na verificação seguinte e a mensagem chega ao canal. Se nada chegar, verifique primeiro os logs do relay: eles registram todos os payloads convertidos, incluindo qualquer rejeição do Teams.

Formato do payload: o Toqan Router envia por POST o envelope de notificação como application/json com os cabeçalhos X-Orq-Hook-ID, X-Orq-Event e Idempotency-Key, além de quaisquer cabeçalhos configurados no notificador:

JSON

{
  "id": "ntf_01JQ8Z2K4M6P8R0T2V4X6Z8B0D",
  "version": 1,
  "workspace_id": "ws_01JQ8Z0MB5W1YTVN3GCK7B0EXA",
  "timestamp": "2026-08-08T09:30:00Z",
  "title": "Budget usage has reached your notification threshold",
  "body": "Your usage today for workspace acme has reached $92.00 (92%) of your $100.00 budget. This alert is configured at 90% ($90.00).",
  "severity": "warning",
  "links": [
    { "text": "Manage budgets", "url": "https://router.toqan.ai/eu/budgets" }
  ],
  "tags": {
    "budget_id": "bgt_01JQ8Z0MB5W1YTVN3GCK7B0EXA",
    "scope_kind": "WORKSPACE",
    "period": "DAILY",
    "threshold_percent": "90"
  }
}

O Teams rejeita esse envelope com HTTP 400 porque espera um message card com @type e @context. O relay converte o envelope para esse formato antes de encaminhá-lo. Solução de problemas:

Sintoma	Causa
O Teams responde com `400`	O relay está ausente ou mal configurado. Confirme se o relay realmente mapeia o envelope para um MessageCard antes de verificar qualquer outra coisa.
Nada chega ao canal	A URL do webhook está desatualizada ou foi revogada, ou o relay falhou. Verifique nos logs do relay as solicitações entregues e rejeitadas.
As notificações chegam com atraso	Respostas que não são `2xx` são reenviadas, portanto um relay com falha atrasa a entrega até se recuperar.

Níveis de orçamento e interação

Os orçamentos podem ser definidos em seis níveis: Workspace, Project, Identity, API Key, Provider e Model. Quando vários orçamentos se aplicam à mesma solicitação, cada um deles é aplicado de forma independente e cumulativa. Não há precedência: um orçamento em um nível nunca substitui um orçamento em outro nível, e uma solicitação precisa atender a todos os orçamentos que correspondem a ela. Como é permitido apenas um orçamento por alvo (consulte Criar um orçamento), uma solicitação pode corresponder a no máximo um orçamento com escopo por nível, até seis orçamentos com escopo no total, além de todos os orçamentos cuja expressão de correspondência ela satisfaça. Quando um orçamento se esgota, apenas as solicitações que correspondem a ele são rejeitadas.

Escopo por expressão (API)

A API também aceita uma expressão CEL match no lugar de um escopo estruturado, para alvos que os seis níveis não cobrem. A expressão é avaliada em relação ao contexto da solicitação, e o orçamento se aplica quando ela retorna true. match e scope são mutuamente exclusivos.

JSON

{
  "match": { "cel": "metadata.team == \"ml\" && provider == \"openai\"" },
  "limits": { "period": "BUDGET_PERIOD_MONTHLY", "amount": 100 }
}

Variáveis disponíveis: model, provider, model_id, api_key, identity, project, metadata (map) e headers (map, chaves em minúsculas). Envie match ou scope, nunca ambos: uma expressão vazia é rejeitada, a menos que o orçamento seja criado a partir de um escopo. Um orçamento para todo o workspace armazena a expressão que corresponde a todas as solicitações do workspace.

Como vários orçamentos interagem

Todo orçamento aplicável é imposto. Uma solicitação precisa passar por todos os orçamentos que correspondem a ela. Nenhum orçamento substitui outro.
Cada orçamento acompanha seu próprio uso. Uma solicitação é contabilizada em todos os orçamentos que se aplicam a ela, ao mesmo tempo.
O orçamento mais restritivo prevalece. O teto efetivo de uma dimensão é o do orçamento aplicável mais restritivo. Limites em dimensões diferentes (custo, tokens, solicitações por minuto) se aplicam simultaneamente.
As solicitações por minuto são aplicadas por orçamento, cada um com sua própria janela de 60 segundos, que começa com a primeira solicitação.
Orçamentos expirados deixam de ser aplicados. Após a data de expiração, um orçamento não bloqueia mais solicitações, embora permaneça na lista.

O que é contabilizado em um orçamento

O uso é contabilizado em todos os orçamentos que correspondem a uma solicitação depois que o Toqan Router a conclui. O custo é contabilizado pelo preço de tabela do modelo; os tokens, pelo uso informado pelo provedor.

Origem	Contabilizado	Observação
Chamadas de modelo do AI Gateway	Sim	Chat, Responses, embeddings, imagens, áudio, classify, OCR, rerank, batches e web search contabilizam custo e tokens em todos os orçamentos correspondentes.
Agents e Deployments	Sim	As chamadas de modelo feitas por uma execução de Agent ou Deployment são contabilizadas como qualquer outra solicitação do Gateway.
Chamadas de LLM-judge de Evaluators	Sim	As chamadas de judge verificam os orçamentos que correspondem ao modelo e ao escopo delas e são contabilizadas da mesma forma.
BYOK e modelos privados	Sim	Os tokens são contabilizados, e o custo é contabilizado pelo preço de tabela do modelo, mesmo que a solicitação não consuma créditos.
Experiments	Parcialmente	Os orçamentos não controlam a execução do experimento em si, mas as chamadas de modelo feitas pelas tarefas de Agent dele são contabilizadas nos orçamentos de workspace, projeto, provedor e modelo. Os orçamentos de Identity e de API key não recebem uso de experimentos.
Spans ingeridos por OpenTelemetry e SDK	Não	O Toqan Router não intermediou a chamada, então o span é um dado de observabilidade e não contabiliza uso.

Por que um orçamento pode mostrar $0 enquanto os traces mostram custo

Sintoma	Causa
O uso permanece em $0.00	O tráfego está fora do escopo do orçamento. Compare o destino Project, Identity, API key, Provider ou Model do orçamento com o trace.
O uso de experimentos aparece em um orçamento de workspace, projeto, provedor ou modelo, mas não em um orçamento de Identity ou de API key	As execuções de experimentos não têm atribuição de identity nem de API key, então esses escopos não registram nada. As mesmas chamadas de modelo são contabilizadas nos outros orçamentos correspondentes.
O uso permanece em $0.00 para spans ingeridos por OpenTelemetry ou SDK	Esses spans descrevem chamadas que o Toqan Router não intermediou, então não contabilizam uso.
O uso permanece em $0.00 depois de criar um orçamento	O uso começa a ser contabilizado na próxima solicitação correspondente. Gastos ocorridos antes da criação do orçamento não são contabilizados.
O uso volta para $0.00	O período de redefinição foi renovado. O card mostra apenas o uso do período atual.
Um trace mostra custo enquanto o card do orçamento mostra $0	Gastos abaixo de um centavo são arredondados para `$0` no card. Passe o cursor sobre o valor para ver as casas decimais exatas.

Exemplos práticos

Orçamento do workspace mais um orçamento por projeto

O workspace tem um orçamento de $1.000/mês. O projeto Production tem um orçamento de $300/mês.

As solicitações ao Production são contabilizadas nos dois orçamentos; as solicitações a outros projetos são contabilizadas apenas no orçamento do workspace.
Quando o Production atinge $300, as solicitações ao Production são rejeitadas até a redefinição mensal. Os outros projetos continuam funcionando até que o orçamento do workspace se esgote em $1.000.

Orçamento por identidade dentro de um projeto com orçamento próprio

O projeto Support tem um orçamento de $500/mês. A identidade customer-acme tem um orçamento de $50/mês.

O orçamento da identidade se aplica a todos os projetos: o teto de $50/mês é aplicado sempre que customer-acme faz uma solicitação, independentemente do projeto.
As solicitações de customer-acme são contabilizadas nos dois orçamentos. Quando o orçamento da identidade se esgota, essas solicitações são rejeitadas mesmo que o orçamento do projeto ainda tenha saldo; as outras identidades continuam funcionando.

Orçamento por modelo junto com um teto para todo o workspace

O workspace tem um orçamento de $2.000/mês. O modelo anthropic/claude-sonnet-5 tem um orçamento de $800/mês.

Quando o orçamento do modelo se esgota, as solicitações a esse modelo são rejeitadas; os outros modelos continuam funcionando.
Quando o gasto total do workspace atinge $2.000, todas as solicitações são rejeitadas até a redefinição mensal, independentemente do modelo.

Quando um limite é excedido

Uma solicitação que corresponde a um orçamento esgotado é rejeitada com 429 Too Many Requests. A resposta identifica o orçamento e a dimensão excedida (cost, tokens ou requests); os cabeçalhos da resposta informam o limite, o uso restante e os segundos até a redefinição. Apenas as solicitações que correspondem ao orçamento esgotado são bloqueadas.

Dimensão	Comportamento quando excedido
Cost e Tokens	Os contadores são atualizados à medida que as solicitações são concluídas. Quando um orçamento atinge 100%, a próxima solicitação correspondente é rejeitada. As solicitações permanecem bloqueadas até que o período do orçamento seja redefinido ou que um administrador aumente o limite.
Requests per minute	As solicitações são rejeitadas pelo restante da janela atual de 60 segundos, independentemente do período de redefinição.

Para orçamentos com período de redefinição One-time, não há redefinição automática: as solicitações correspondentes permanecem bloqueadas até que um administrador aumente o limite, exclua o orçamento ou a data de expiração seja atingida.

Períodos de redefinição

Cada orçamento tem seu próprio período de redefinição e seus próprios contadores. Orçamentos em níveis diferentes podem usar períodos diferentes: Daily, Weekly, Monthly, Yearly ou One-time (sem redefinição). Consulte Criar um orçamento para ver o cronograma de redefinição.

Veja também

Limites de taxa e cotas

O que o próprio AI Gateway aplica em comparação com os provedores upstream, e o contrato da resposta 429.

Chaves de API

Crie e gerencie chaves de API do AI Gateway com limites de gastos opcionais.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Visão geral

Monitorar o uso

Criar um orçamento

Editar ou excluir um orçamento

Configurar alertas

Criar um notificador

Criar um alerta

Exemplos

Enviar notificações para um canal do Microsoft Teams

Níveis de orçamento e interação

Escopo por expressão (API)

Como vários orçamentos interagem

O que é contabilizado em um orçamento

Por que um orçamento pode mostrar $0 enquanto os traces mostram custo

Exemplos práticos

Quando um limite é excedido

Períodos de redefinição

Veja também

Limites de taxa e cotas

Chaves de API

​Visão geral

​Monitorar o uso

​Criar um orçamento

​Editar ou excluir um orçamento

​Configurar alertas

​Criar um notificador

​Criar um alerta

​Exemplos

​Enviar notificações para um canal do Microsoft Teams

​Níveis de orçamento e interação

​Escopo por expressão (API)

​Como vários orçamentos interagem

​O que é contabilizado em um orçamento

​Por que um orçamento pode mostrar $0 enquanto os traces mostram custo

​Exemplos práticos

​Quando um limite é excedido

​Períodos de redefinição

​Veja também

Limites de taxa e cotas

Chaves de API

Visão geral

Monitorar o uso

Criar um orçamento

Editar ou excluir um orçamento

Configurar alertas

Criar um notificador

Criar um alerta

Exemplos

Enviar notificações para um canal do Microsoft Teams

Níveis de orçamento e interação

Escopo por expressão (API)

Como vários orçamentos interagem

O que é contabilizado em um orçamento

Por que um orçamento pode mostrar $0 enquanto os traces mostram custo

Exemplos práticos

Quando um limite é excedido

Períodos de redefinição

Veja também