Vai al contenuto principale
I contatori convertono eventi grezzi in quantità fatturabili. Filtrano gli eventi e applicano funzioni di aggregazione (Count, Sum, Max, Last) per calcolare l’utilizzo per cliente.
Interfaccia di creazione del misuratore che mostra il nome dell'evento, il tipo di aggregazione e le opzioni di filtraggio

​
Risorse API

Create Meter

Crea contatori in modo programmatico tramite API.

List Meters

Recupera tutti i contatori nel tuo account.

Get Meter

Recupera i dettagli di uno specifico contatore tramite ID.

Archive Meter

Archivia un contatore per interrompere il monitoraggio dell’utilizzo.

Unarchive Meter

Ripristina un contatore archiviato per riprendere il monitoraggio.

​
Creazione di un Misuratore

1

Basic Information

​
Meter Name
string
obbligatorio
Nome descrittivo (es. “API Requests”, “Token Usage”)
​
Event Name
string
obbligatorio
Nome esatto dell’evento da corrispondere (sensibile alle maiuscole). Esempi: api.call, image.generated
2

Aggregation

​
Aggregation Type
string
obbligatorio
Scegli come vengono aggregati gli eventi:
  • Count: numero totale di eventi (chiamate API, upload)
  • Sum: somma dei valori numerici (token, byte)
  • Max: valore massimo nel periodo (picco utenti)
  • Last: valore più recente
​
Over Property
string
Chiave dei metadati da aggregare (richiesta per tutti i tipi tranne Count). Esempi: tokens, bytes, duration_ms
​
Measurement Unit
string
obbligatorio
Etichetta dell’unità per le fatture. Esempi: calls, tokens, GB, hours
3

Filtering (Optional)

Filtraggio eventi
Aggiungi condizioni per filtrare quali eventi vengono conteggiati:
  • Logica AND: Tutte le condizioni devono corrispondere
  • Logica OR: Qualsiasi condizione può corrispondere
Comparatori: uguale, diverso, maggiore di, minore di, contieneAbilita il filtraggio, scegli la logica e aggiungi condizioni con chiave della proprietà, comparatore e valore.
4

Create

Controlla la configurazione e fai clic su Create Meter.

​
Visualizzazione Analitiche

Analisi del misuratore
Il tuo cruscotto dei misuratori mostra:
  • Panoramica: Utilizzo totale e grafico dell’utilizzo
  • Eventi: Eventi individuali ricevuti
  • Clienti: Utilizzo e addebiti per cliente

​
Fatturazione in crediti invece che in valuta

Di default, i contatori addebitano i clienti per unità in dollari (o nella valuta configurata). Puoi invece configurare un contatore per dedurre da un saldo di crediti: così l’utilizzo consuma crediti anziché generare un addebito monetario.
La deduzione basata sui crediti richiede un Credit Entitlement collegato allo stesso prodotto. Crea prima il tuo credito, poi collegalo al contatore.

​
Quando usare la deduzione basata sui crediti

​
Configurare un contatore per dedurre crediti

1

Create a Credit Entitlement

Per prima cosa, crea un credito in Prodotti → Crediti. Definisci l’unità (ad es. “API Calls”, “Tokens”), la precisione e le impostazioni del ciclo di vita (scadenza, rollover, overage).Consulta la Guida alla fatturazione basata sui crediti per istruzioni dettagliate.
2

Create or Edit a Usage-Based Product

Vai al tuo prodotto basato sull’utilizzo e apri la sezione di configurazione del Contatore.
3

Add a Meter

Fai clic sul pulsante + per collegare un contatore. Configura il nome dell’evento, il tipo di aggregazione e l’unità di misura come sempre.
4

Enable 'Bill Usage in Credits'

Attiva Fattura utilizzo in crediti nella configurazione del contatore. Questo rivela le impostazioni del credito:
Configurazione del misuratore con l'opzione Fattura utilizzo in Crediti abilitata

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

​
Credit Entitlement
string
obbligatorio
Seleziona quale Credit Entitlement deve essere utilizzato da questo contatore.
​
Meter units per credit
number
obbligatorio
Il numero di unità di utilizzo necessario per dedurre 1 credito. Ad esempio:
  • 1 = ogni evento del contatore deduce 1 credito
  • 100 = 100 eventi del contatore deducono 1 credito
  • 1000 = 1.000 chiamate API consumano 1 credito
5

Set the Free Threshold

La Soglia gratuita è ancora applicabile: gli eventi al di sotto di questa soglia non deducono crediti.Esempio: con soglia gratuita di 1.000 e unità del contatore per credito pari a 1:
  • Il cliente utilizza 2.500 chiamate API
  • Le prime 1.000 sono gratuite
  • Le restanti 1.500 deducono 1.500 crediti dal loro saldo

​
Come funziona la deduzione dei crediti

Una volta configurata, la pipeline di deduzione viene eseguita automaticamente:
  1. Arrivo degli eventi - La tua applicazione invia eventi di utilizzo tramite l’Event Ingestion API
  2. Aggregazione del contatore - Gli eventi vengono aggregati in base alla configurazione del contatore (Count, Sum, Max, Last)
  3. Elaborazione dal worker in background - Ogni minuto, un worker recupera i nuovi eventi dall’ultimo checkpoint
  4. I crediti vengono dedotti - L’utilizzo aggregato viene convertito in crediti tramite il tasso meter_units_per_credit e dedotto usando l’ordinamento FIFO (i grant più vecchi vengono consumati per primi)
  5. Monitoraggio degli overage - Se il saldo raggiunge zero e l’overage è abilitato, l’utilizzo continua e l’overage viene gestito secondo il comportamento configurato (ignorato al reset, fatturato alla fattura successiva o riportato come deficit)
La deduzione dei crediti viene eseguita in modo asincrono (ogni ~1 minuto). Potrebbe esserci un breve ritardo tra l’ingestione degli eventi e la deduzione dal saldo. Progetta la tua applicazione per gestire questo ritardo: non basarti su controlli di saldo in tempo reale per il controllo accessi su singole richieste.

​
Più contatori, un unico pool di crediti

Puoi collegare più contatori dello stesso prodotto allo stesso credit entitlement. Tutti i contatori prelevano da un saldo condiviso. Esempio: una piattaforma AI con due contatori:
  • text.generation - 1 credito ogni 1.000 token
  • image.generation - 10 crediti per immagine
Entrambi deducono dallo stesso pool “AI Credits”. Il cliente vede un unico saldo unificato nel portale.
Usa tassi meter_units_per_credit differenti tra i contatori per esprimere costi relativi. Le operazioni costose (generazione di immagini) richiedono meno unità del contatore per credito rispetto a quelle economiche (completamento di testo).

List Customer Ledger

Visualizza l’intera cronologia di deduzione dei crediti per un cliente.

Get Customer Balance

Controlla il saldo di crediti attuale di un cliente tramite API.

​
Risoluzione dei problemi

  • Il nome dell’evento deve corrispondere esattamente (distinzioni tra maiuscole e minuscole)
  • Controlla che i filtri del contatore non stiano escludendo gli eventi
  • Verifica che gli ID dei clienti esistano
  • Disabilita temporaneamente i filtri per testare
  • Verifica che Over Property corrisponda esattamente alla chiave dei metadati
  • Usa numeri, non stringhe: tokens: 150 invece di "150"
  • Includi le proprietà richieste in tutti gli eventi
  • Rispetta esattamente le maiuscole/minuscole
  • Usa gli operatori corretti per il tipo di dato
  • Assicurati che gli eventi includano le proprietà filtrate
  • Controlla la scheda Eventi per contare gli eventi effettivamente ricevuti
  • Verifica il tipo di aggregazione (Count vs Sum)
  • Assicurati che i valori siano numerici per Sum/Max

​
Prossimi passi

Send Events

Inizia a inviare eventi di utilizzo dalla tua applicazione ai contatori.

View Blueprints

Usa configurazioni di contatori preconfezionate per casi d’uso comuni.
Ultima modifica il 20 aprile 2026