Free tool

Usage Event Schema Generator

Describe what you bill on and get a ready-to-send usage event: JSON payload plus cURL, Node.js, Python and Go code for the MetricaOS ingest API.

1. What happened?

Pick a common event type, or define your own.

2. Metrics

The numbers you meter and bill on.

3. Customer & metadata

sent as metadata.customer_id so usage is billed to that customer

Your event

Send with a POST request and an X-API-Key header. The API replies 202 Accepted.

JSON payload

          
Code

          

            
            
            
            
          

          

          
API reference

          
Create an API key with the events:write scope in the MetricaOS dashboard. Event IDs are idempotency keys: a repeated eventId is ignored, so retries are safe. Use a unique ID per billable action.

        

      

    

  






  

    

      
Send your first event in minutes

      
Create a free MetricaOS account, generate an API key and start metering usage per customer. Free plan included, no credit card.

      Start free with MetricaOS
    

  






  

    

      
Designing good usage events

      
A usage event is a small, immutable record of one billable action: which customer, which product or model, and how much was consumed. Everything downstream (cost tracking, quotas, invoices, margin analysis) is built from this stream, so it pays to get the shape right early.

      
    
        
  • One event per billable action with numeric metrics such as input_tokens, output_tokens, images or audio_seconds.
    • 
        
  • A stable unique ID so retries never double-count.
    • 
        
  • The customer on every event, set at the source rather than inferred later.
    • 
        
  • Metadata for slicing: feature, environment, plan. Keep it low-cardinality.
    • 
      

      
Read more in the glossary: usage event, token metering and billable usage.

    

  






  

    
Frequently asked questions

    

      

        
        

          

            
Sign in to MetricaOS and create a key under Settings → API Keys. Give it the events:write scope for ingestion. Keep it on your server and never expose it in browser code.

          

        

      


      

        
        

          

            
Include the customer's ID as metadata.customer_id. MetricaOS uses it to attribute usage and deduct from that customer's balance.

          

        

      


      

        
        

          

            
Events are deduplicated on eventId, so a retried request does not create a second charge.

          

        

      


      

        
        

          

            
No. It only generates code in your browser. Nothing is sent to MetricaOS until you run the code with your own API key.