What is a usage event?
A usage event is a structured record of something measurable that happened inside a product.
For an AI application, a usage event might record that a customer:
- generated a response
- summarized a document
- processed an image
- ran an AI agent
- consumed tokens
- made an API request
- used a certain amount of compute
A usage event usually contains two kinds of information:
Metrics, which describe how much was consumed.
Context, which describes who or what generated the usage.
Together, these allow an AI product to turn raw activity into reliable AI usage metering, cost attribution, limits, pricing, and billing.
What does a usage event contain?
The exact fields depend on the product, but an AI usage event might look like this:
{
"event_id": "evt_123",
"event_type": "completion",
"customer_id": "cus_456",
"user_id": "usr_789",
"provider": "openai",
"model": "gpt-5",
"feature": "document_summary",
"metrics": {
"input_tokens": 4200,
"output_tokens": 650,
"total_tokens": 4850,
"cost_usd": 0.036
},
"timestamp": "2026-10-03T10:30:00Z"
}The event tells the metering system what happened, who used it, and how much usage occurred.
Metrics vs context
A useful usage-event design separates metrics from descriptive context.
Metrics
Metrics are measurable quantities such as:
- input tokens
- output tokens
- requests
- images generated
- audio minutes
- documents processed
- GPU hours
- estimated cost
For LLM products, token metering often provides some of the most important usage metrics.
Context
Context explains where the usage belongs.
Common fields include:
customer_id
user_id
workspace_id
provider
model
feature
event_type
request_idThis context is what allows teams to move beyond total usage and answer questions such as:
Which customer generated this cost?
Which feature consumed the most tokens?
Which model is driving usage?
Which workspace is approaching its limit?
Why customer identity matters
One of the most important fields in a usage event is usually the customer identifier.
Imagine your provider reports:
Total monthly AI cost: $8,000
That tells you how much you spent.
But if your events include customer_id, you can instead understand:
Customer A: $1,400
Customer B: $380
Customer C: $52
That makes the data useful for cost per customer, profitability analysis, plan design, and customer-level billing.
Without customer attribution, usage data is much less commercially useful.
Usage events and LLM cost tracking
A usage event can also contain enough information to estimate the cost of an AI request.
For example:
Provider: OpenAI
Model: GPT-5
Input tokens: 4,200
Output tokens: 650
Estimated cost: $0.036The token counts describe consumption.
The provider and model determine which pricing should apply.
The resulting cost can then feed LLM cost tracking and customer-level profitability analysis.
The important point is that cost should remain connected to the event that created it.
That makes later reporting and reconciliation much easier.
Real-time vs batch usage events
Usage events do not always need to arrive one at a time.
Real-time ingestion
Real-time events are useful when the product needs to update:
- credit balances
- quotas
- usage dashboards
- alerts
- overage status
soon after the activity occurs.
Batch ingestion
Batch ingestion can be useful for:
- historical data
- backfills
- delayed pipelines
- aggregated systems
- importing usage from another service
The underlying event structure can remain the same even if the delivery method changes.
MetricaOS supports both single-event and batch ingestion in its usage workflow, allowing teams to send structured usage data while keeping the same underlying schema.
Why usage events need unique identifiers
A usage-based billing system should avoid counting the same event twice.
Imagine an application sends a usage event, does not receive the expected response, and retries the request.
Without a unique event identifier, the same activity could potentially be counted twice.
A field such as:
event_id: evt_123gives the metering system a way to recognize duplicate submissions.
This concept is often called idempotency or deduplication.
The implementation can vary, but the principle is simple:
One real product action should normally create one billable usage record, even if the event is submitted more than once.
Usage event vs billable usage
A usage event does not automatically mean the customer should be charged.
An event may represent:
- free trial usage
- internal testing
- a failed operation
- a retry
- promotional usage
- included subscription usage
- overage usage
So it is useful to separate:
Usage event
↓
Metered usage
↓
Priced / rated usage
↓
Billable usageThe usage event records reality.
Commercial rules determine what that reality means for pricing.
This distinction is fundamental to usage-based billing.
Why usage events should be designed before billing
Many teams start by designing pricing plans first.
But if the underlying usage data is incomplete, the billing system eventually becomes difficult to operate.
For example, if you do not record the customer, model, feature, or relevant metric when an event happens, it may be impossible to reconstruct that information accurately later.
A better approach is:
Capture usage first. Preserve context. Apply pricing later.
This is the architecture described in How to Implement Usage-Based Billing for AI Services.
Common usage-event mistakes
A common mistake is recording only aggregate totals.
Knowing that the product consumed 10 million tokens this month is useful, but it does not explain which customers or features generated them.
Another mistake is creating a schema that is too rigid. AI products often add new models, providers, metrics, and workflows over time.
Teams can also run into problems when events do not have stable identifiers, making duplicate detection more difficult.
Finally, usage events should not contain only billing information. They should preserve the underlying activity accurately so the same data can support analytics, cost tracking, pricing, and billing.
How MetricaOS handles usage events
MetricaOS uses structured usage events as the foundation of its metering layer.
Teams can define metric fields and event fields, ingest usage individually or in batches, and attach product context such as customers, providers, models, and other dimensions. The Event Schema and ingestion screens in MetricaOS are designed around this separation between measurable metrics and contextual fields.
Those events can then support cost analysis, credit rules, usage limits, customer wallets, billing, and profitability reporting.
A good usage event may look simple.
But it is the record that connects what happened inside the AI product to everything that comes afterward.