Usage event

In Zenskar, a usage event is the atomic record of customer activity. It serves as the raw data input for usage-based (metered) pricing models. While a contract defines the price per unit, a usage event records the actual consumption of those units, such as API calls made, gigabytes stored, or minutes streamed.

Usage events provide the objective evidence of consumption required to generate accurate invoices for variable-rate products.

Anatomy of a usage event

Every usage event is a structured data point composed of three primary elements. This structure ensures that activity is accurately attributed and available for complex calculations.

Customer identity (customer_id): A unique identifier that links the event to a specific customer and their associated contract.
Temporal placement (timestamp): A precise timestamp, recorded in DateTime64 format, indicating exactly when the activity occurred. This ensures usage is billed in the correct billing cycle.
Data payload (data): A flexible JSON-like container for the actual usage details. This allows you to send any relevant key-value pairs required for your pricing logic, such as request_size or region.

Event types

Zenskar ingests usage data in two distinct formats, depending on how your upstream systems track and report activity.

Granular usage events: Raw, individual units of activity. For example: "User A streamed 1 minute at 11:34 PM." Zenskar performs the aggregation for these events at the end of the billing period.
Pre-aggregated usage events: Pre-summarized activity from your infrastructure. For example: "User A streamed 1,000 minutes this month." Useful when your source system already performs high-volume calculations before sending data to Zenskar.

Standard aggregation types

Usage events are not billed individually. Instead, Zenskar looks at the collection of events within a billing period and applies an aggregate function to derive a single billable metric.

Aggregate	Description	Example use case
SUM	Adds the values of all events in the period.	Total gigabytes transferred.
COUNT	Counts the number of events in the period.	Total API calls made.
MAX	Takes the highest value recorded in the period.	Peak concurrent users.
MIN	Takes the lowest value recorded in the period.	Minimum committed throughput.
UNIQUE COUNT	Counts the number of distinct values in the period.	Unique active users.

flowchart LR
    subgraph Input [Usage event types]
        Granular[Granular events]
        Aggregated[Pre-aggregated events]
    end

    subgraph Processing [Aggregation]
        Aggregator[SQL aggregation: SUM, COUNT, MIN, MAX, etc.]
    end

    subgraph Outputs [Outputs]
        Metrics[Billable metrics]
        Invoicing[Invoice generation]
    end

    Granular --> Aggregator
    Aggregator --> Metrics
    Aggregated --> Metrics
    Metrics --> Invoicing

Relationship to the product hierarchy

In the Zenskar data model, usage events serve as the input for the product defined within a phase.

The contract establishes that a customer is using a specific product.
The product defines the price and the aggregate function to apply (e.g., "Sum of gigabytes").
The usage events provide the raw numbers.
The billing engine calculates the final billable metric and generates the corresponding invoice line item.

Next steps:

To learn how to move usage data from your systems to Zenskar, see the [Usage ingestion] concept page.
For a technical breakdown of usage event fields, see the [Usage event API reference].