Medidores

Transforme eventos de uso brutos em quantidades faturáveis com agregação e filtragem.

Os medidores convertem eventos brutos em quantidades faturáveis. Eles filtram eventos e aplicam funções de agregação (Count, Sum, Max, Last) para calcular o uso por cliente.

​

Recursos da API

View Meter API References

Create Meter

Crie medidores programaticamente via API.

List Meters

Recupere todos os medidores em sua conta.

Get Meter

Obtenha detalhes de um medidor específico por ID.

Archive Meter

Arquive um medidor para parar de rastrear o uso.

Unarchive Meter

Restaure um medidor arquivado para retomar o rastreamento.

​

Criando um Medidor

1. Basic Information

   Meter Name · string · obrigatório

   Nome descritivo (por exemplo, “API Requests”, “Token Usage”)

   Event Name · string · obrigatório

   Nome exato do evento para corresponder (diferencia maiúsculas/minúsculas). Exemplos: api.call, image.generated

2. Aggregation

   Aggregation Type · string · obrigatório

   Escolha como os eventos são agregados:

   • Count: Número total de eventos (chamadas de API, uploads)
   • Sum: Some valores numéricos (tokens, bytes)
   • Max: Maior valor no período (usuários máximos)
   • Last: Valor mais recente

   Over Property · string

   Chave de metadados para agregar (obrigatória para todos os tipos, exceto Count). Exemplos: tokens, bytes, duration_ms

   Measurement Unit · string · obrigatório

   Rótulo da unidade para faturas. Exemplos: calls, tokens, GB, hours

3. Filtering (Optional)

   

   Adicione condições para filtrar quais eventos são contados:

   • Lógica AND: Todas as condições devem corresponder
   • Lógica OR: Qualquer condição pode corresponder

   Comparadores: igual, diferente, maior que, menor que, contém

   Ative a filtragem, escolha a lógica, adicione condições com chave de propriedade, comparador e valor.

4. Create

   Revise a configuração e clique em Create Meter.

​

Visualizando Análises

Seu painel de medidores mostra:

• Visão Geral: Uso total e gráfico de uso
• Eventos: Eventos individuais recebidos
• Clientes: Uso e cobranças por cliente

​

Cobrança em Créditos em vez de Moeda

Por padrão, os medidores cobram os clientes por unidade em dólares (ou na sua moeda configurada). Você pode configurar um medidor para deduzir de um saldo de créditos - assim o uso consome créditos em vez de gerar uma cobrança monetária.

A dedução baseada em créditos exige um Credit Entitlement vinculado ao mesmo produto. Crie seu crédito primeiro e, em seguida, vincule-o ao medidor.

​

Quando usar dedução baseada em créditos

Cenário	Padrão (moeda)	Baseado em Créditos
Precificação simples por unidade ($0,01/chamada)	✅ Melhor opção	Sobrecarga desnecessária
Pacotes de crédito pré-pagos (compre 10K tokens, use ao longo do tempo)	❌ Não é possível expressar	✅ Melhor opção
Uso incluído em assinatura (plano Pro inclui 100K chamadas)	Possível com limite gratuito	✅ Melhor – créditos acumulam, expiram e aparecem no portal
Produtos com múltiplos medidores compartilhando um pool de créditos	❌ Cada medidor fatura separadamente	✅ Todos os medidores deduzem de um único saldo

​

Configurando um medidor para deduzir créditos

1. Create a Credit Entitlement

   Primeiro, crie um crédito em Products → Credits. Defina a unidade (por exemplo, “API Calls”, “Tokens”), a precisão e as configurações de ciclo de vida (expiração, rollover, excedente).

   Consulte o guia de Faturamento Baseado em Créditos para obter instruções detalhadas.

2. Create or Edit a Usage-Based Product

   Acesse seu produto baseado em uso e abra a seção de configuração do Meter.

3. Add a Meter

   Clique no botão + para anexar um medidor. Configure o nome do evento, o tipo de agregação e a unidade de medição como de costume.

4. Enable 'Bill Usage in Credits'

   Ative Cobrar uso em Créditos na configuração do medidor. Isso revela as configurações de crédito:

   

   Toggle 'Bill usage in Credits' to switch from currency-based to credit-based deduction.

   Credit Entitlement · string · obrigatório

   Selecione de qual Credit Entitlement este medidor deve deduzir.

   Meter units per credit · number · obrigatório

   O número de unidades de uso necessárias para deduzir 1 crédito. Por exemplo:

   • 1 = cada evento do medidor deduz 1 crédito
   • 100 = 100 eventos do medidor deduzem 1 crédito
   • 1000 = 1.000 chamadas de API consomem 1 crédito
5. Set the Free Threshold

   O Limite Gratuito ainda se aplica - eventos abaixo desse limite não deduzem créditos.

   Exemplo: Com um limite gratuito de 1.000 e unidades de medidor por crédito igual a 1:

   • O cliente usa 2.500 chamadas de API
   • As primeiras 1.000 são gratuitas
   • As 1.500 restantes deduzem 1.500 créditos do saldo dele

​

Como a dedução de créditos funciona

Uma vez configurado, o pipeline de dedução é executado automaticamente:

1. Os eventos chegam - Sua aplicação envia eventos de uso por meio da Event Ingestion API
2. O medidor agrega - os eventos são agregados de acordo com a configuração do medidor (Count, Sum, Max, Last)
3. Processamento por worker em background - a cada minuto, um worker busca novos eventos desde o último checkpoint
4. Créditos são deduzidos - o uso agregado é convertido em créditos usando a taxa meter_units_per_credit e deduzido seguindo a ordem FIFO (as concessões mais antigas são consumidas primeiro)
5. Excesso é monitorado - se o saldo atingir zero e o excedente estiver ativado, o uso continua e o excedente é tratado conforme o comportamento configurado (perdoado no reset, cobrado na próxima fatura ou levado como déficit)

A dedução de créditos é executada de forma assíncrona (a cada ~1 minuto). Pode haver um pequeno atraso entre a ingestão do evento e a dedução no saldo. Projete sua aplicação para lidar com esse atraso - não dependa de verificações de saldo em tempo real para controle de acesso em requisições individuais.

​

Vários medidores, um pool de créditos

Você pode vincular múltiplos medidores no mesmo produto ao mesmo Credit Entitlement. Todos os medidores deduzem de um único saldo compartilhado.

Exemplo: Uma plataforma de IA com dois medidores:

• text.generation - 1 crédito por 1.000 tokens
• image.generation - 10 créditos por imagem

Ambos deduzem do mesmo pool “AI Credits”. O cliente vê um único saldo unificado em seu portal.

Use diferentes taxas meter_units_per_credit entre os medidores para expressar custos relativos. Operações caras (geração de imagens) exigem menos unidades de medidor por crédito do que operações baratas (completação de texto).

List Customer Ledger

Veja o histórico completo de dedução de créditos de um cliente.

Get Customer Balance

Verifique o saldo atual de créditos de um cliente via API.

​

Solução de problemas

Events not appearing

• O nome do evento deve coincidir exatamente (considerando maiúsculas e minúsculas)
• Verifique se os filtros do medidor não estão excluindo os eventos
• Verifique se os IDs dos clientes existem
• Desative temporariamente os filtros para testar

Aggregation not working

• Verifique se a Over Property corresponde exatamente à chave de metadata
• Use números, não strings: tokens: 150 não "150"
• Inclua as propriedades obrigatórias em todos os eventos

Filters not working

• Combine exatamente as maiúsculas e minúsculas
• Use os operadores corretos para o tipo de dado
• Garanta que os eventos incluam as propriedades filtradas

Wrong usage totals

• Verifique a aba Eventos para contar os eventos reais recebidos
• Verifique o tipo de agregação (Count vs Sum)
• Garanta que os valores sejam numéricos para Sum/Max

​

Próximos passos

Send Events

Comece a enviar eventos de uso da sua aplicação para os seus medidores.

View Blueprints

Use configurações prontas de medidores para casos de uso comuns.