Events & Metering

Usage-based billing starts with events — signals from your application that tell Brilo something billable happened. Brilo aggregates those events into metrics, and metrics drive pricing components on your plans.

What Is an Event?

An event represents a single billable action by a customer. Examples:

• A user made an API call
• A message was sent
• A file was processed
• A report was generated
• A seat was used in a billing period

Events are lightweight and schema-flexible. You define the event name and attach any properties that might be useful for billing or filtering.

The Event Object

{
  "event_name": "api_call_made",
  "customer_id": "cust_123",
  "idempotency_id": "evt_abc123",
  "time_created": "2024-05-01T10:00:00Z",
  "properties": {
    "endpoint": "/v1/messages",
    "tokens_used": 1200,
    "model": "gpt-4"
  }
}

Tracking Events

Send events to the Track an Event endpoint:

curl -X POST https://api.brilo.tech/api/track \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "message_sent",
    "customer_id": "cust_123",
    "idempotency_id": "evt-20240501-001",
    "time_created": "2024-05-01T10:00:00Z",
    "properties": {
      "characters": 2322,
      "size_bytes": 4800
    }
  }'

A successful response returns 200 OK. The event is queued for processing.

Idempotency

The idempotency_id is how Brilo prevents double-counting if your app retries a failed request. If two events arrive with the same idempotency_id, only the first is counted.

Generate idempotency IDs that are:

• Unique per event (not per event type)
• Deterministic — if you generate the same event again, you should get the same ID
• Based on something meaningful: a UUID, a database row ID, or a hash of (customer_id + event_name + timestamp)

import hashlib

def make_idempotency_id(customer_id, event_name, timestamp):
    raw = f"{customer_id}:{event_name}:{timestamp}"
    return hashlib.sha256(raw.encode()).hexdigest()[:32]

Verifying Events Were Received

Use the Verify Events Received endpoint to confirm a batch of events made it to Brilo:

curl -X POST https://api.brilo.tech/api/verify-events \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_ids": ["evt-001", "evt-002", "evt-003"],
    "lookback_days": 3
  }'

The response tells you which IDs were received. Any missing ones should be retried.

Sending Events in Practice

Track at the point of action

Send events as close to the action as possible — ideally synchronously before the response is returned, or asynchronously via a background job immediately after.

Batch with care

You can send events one at a time or in quick succession. Brilo does not have a native batch endpoint — if you need to backfill historical events, send them sequentially and use the time_created field to set the correct timestamp.

Don't bill every event type

You can track any event you want. Events only affect billing when referenced by a metric. This means you can track events for analytics, debugging, or future pricing models without them appearing on invoices.

From Events to Metrics

A metric aggregates events over a billing period and turns them into a single billable number. For example:

Metrics are configured in the dashboard under Metrics → Create Metric, or via the API. Once created, a metric can be attached to a pricing component on any plan.

Aggregation Types

Time Windows

Metrics aggregate over the customer's current billing period. If a customer is on a monthly plan, their metric resets each month. If they're on an annual plan, it accumulates over the year.

You can also filter events by time within a metric definition — for example, only count events that occurred on weekdays, or only sum events above a certain property threshold.

Next Steps