Pular para o conteúdo principal
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.
Interface de criação de medidores mostrando nome do evento, tipo de agregação e opções de filtragem

​
Recursos da API

​
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)

Filtragem de eventos
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émAtive 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

Análise do medidor
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árioPadrão (moeda)Baseado em Créditos
Precificação simples por unidade ($0,01/chamada)✅ Melhor opçãoSobrecarga 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:
Configuração do medidor com a alternância 'Cobrar uso em Créditos' ativada
​
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

  • 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
  • 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
  • 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
  • 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.