Usage Metering

The UsageMeteringService records individual usage events for all billable resources on the platform. Usage records track API calls, query executions, storage consumption, compute time, data transfer, and other measurable activities. These records are aggregated by the UsageAggregationService for billing calculations.

Metric Types

Metric Type	Unit	Description
`API_CALLS`	count	API request invocations
`QUERY_EXECUTIONS`	count	SQL/analytics query executions
`STORAGE_BYTES`	bytes	Data storage consumption
`COMPUTE_SECONDS`	seconds	Compute resource usage
`DATA_TRANSFER_BYTES`	bytes	Network data transfer
`ACTIVE_USERS`	count	Unique active users
`ML_INFERENCE_REQUESTS`	count	ML model inference calls
`DASHBOARD_VIEWS`	count	Dashboard view events
`PIPELINE_RUNS`	count	Data pipeline executions
`CONNECTOR_SYNCS`	count	Data connector sync operations

Record Usage

Endpoint: POST /api/v1/billing/tenants/:tenantId/usage

curl -X POST http://localhost:8087/api/v1/billing/tenants/550e8400/usage \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "metricType": "QUERY_EXECUTIONS",
    "quantity": 1,
    "unit": "count",
    "resourceId": "query-12345",
    "resourceType": "sql_query",
    "userId": "660e8400-e29b-41d4-a716-446655440000",
    "metadata": "{\"queryType\": \"SELECT\", \"rowsReturned\": 1500}"
  }'

Batch Usage Recording

Endpoint: POST /api/v1/billing/tenants/:tenantId/usage/batch

Records multiple usage events in a single request for better throughput.

curl -X POST http://localhost:8087/api/v1/billing/tenants/550e8400/usage/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '[
    {"metricType": "API_CALLS", "quantity": 100, "unit": "count"},
    {"metricType": "DATA_TRANSFER_BYTES", "quantity": 52428800, "unit": "bytes"}
  ]'

Usage Summary

Endpoint: GET /api/v1/billing/tenants/:tenantId/usage/summary

Parameter	Type	Description
`start`	LocalDateTime	Summary period start
`end`	LocalDateTime	Summary period end

curl "http://localhost:8087/api/v1/billing/tenants/550e8400/usage/summary?start=2026-02-01T00:00:00&end=2026-02-28T23:59:59" \
  -H "Authorization: Bearer ${TOKEN}"

UsageRecord Entity

Field	Type	Description
`id`	UUID	Record identifier
`tenantId`	UUID	Owning tenant
`userId`	UUID	User who generated the usage
`metricType`	MetricType	Type of usage metric
`resourceId`	String	Specific resource identifier
`resourceType`	String	Type of resource
`quantity`	BigDecimal	Usage quantity (precision: 20, scale: 6)
`unit`	String	Unit of measurement
`timestamp`	LocalDateTime	When the usage occurred
`metadata`	JSON	Additional context
`aggregated`	boolean	Whether this record has been aggregated
`aggregationPeriod`	String	Aggregation period identifier

Aggregation

The UsageAggregationService periodically aggregates raw usage records into UsageAggregate entries for efficient billing calculations. After aggregation, the aggregated flag is set to true on processed records.

Database Indexes

Index	Columns	Purpose
`idx_usage_tenant_timestamp`	`tenant_id, timestamp`	Tenant usage queries
`idx_usage_metric_timestamp`	`metric_type, timestamp`	Metric-type queries
`idx_usage_aggregated`	`aggregated`	Find un-aggregated records

Architecture Invoices