> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getenso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metering

> Understand the core concepts of metering in Enso, including events, meters, usage, and their relationships.

Enso's metering system is designed to help you track and bill for usage-based metrics. Understanding the core concepts—**events**, **meters**, **usage**, and **invoices**—is essential for modeling your billing accurately.

***

## Key Concepts

### **Events**

**Events** are individual records of activity that represent something happening in your product (e.g., a user logs in, an email is sent, data is stored).\
Events are typically sent to Enso via API or uploaded as CSV files.

**Example event log (CSV):**

| customer\_id | timestamp           | activity | value |
| ------------ | ------------------- | -------- | ----- |
| CUST001      | 2025-05-01T10:00:00 | Log\_in  | 1     |
| CUST001      | 2025-05-01T11:00:00 | Log\_in  | 1     |
| CUST002      | 2025-05-01T12:00:00 | Email    | 1     |

***

### **Meter / Metric**

A **meter** (or metric) defines what you want to measure and bill for.\
A meter **aggregates events** over a given period (such as daily, monthly, or quarterly) to produce a usage value that can be invoiced.

#### **Meter Properties**

* **Aggregation Method:**\
  Determines how events are combined to calculate usage.\
  Common methods:

  * `sum` (total usage)
  * `count` (number of events)
  * `max` (peak usage)
  * `min` (lowest usage)
  * `cumulative_start` (running total from a start date)
  * `cumulative_end` (running total until a reset date)

  If you choose a cumulative aggregation method (`cumulative_start` or `cumulative_end`), you can configure when the meter resets using these fields:

  * **resetType:**
    * `none` (never reset)
    * `annual` (reset every year)
    * `monthly` (reset every month)
    * `custom` (reset on a custom date)
  * **monthOfReset:**\
    Required if `resetType` is `annual`. Select the month when the reset should happen.
  * **dayOfReset:**\
    Required if `resetType` is `annual` or `monthly`. Select the day of the month for the reset.
  * **customDate:**\
    Required if `resetType` is `custom`. Specify the exact date for the reset.

  These options allow you to create meters that automatically reset their aggregation on an anniversary, monthly, or custom schedule.

* **Window Options:**\
  Defines the time period over which events are aggregated.\
  Common windows:
  * Daily
  * Monthly
  * Quarterly

* **Filters:**\
  Allow you to include only specific events in your metric calculation.\
  You can filter on event fields (e.g., browser, region) using logical conditions.

  **Example filter (JSON):**

  ```json theme={null}
  {
    "logic": "and",
    "conditions": [{ "field": "browser", "operator": "eq", "value": "Chrome" }]
  }
  ```

**Examples of meters:**

* Monthly active users (aggregates login events per month)
* GB of storage used (aggregates storage events per month)
* Emails sent (aggregates email events per month)
* Quarterly API calls (aggregates API call events per quarter)

**Meter structure diagram:**

```mermaid theme={null}
flowchart TD
    subgraph Meter Definition
        B[Aggregation Method]
        C[Window]
        D[Filters]
    end
    A[Events] --> C
    A[Events] --> B
    A[Events] --> D
    B --> U[Usage]
    C --> U
    D --> U
```

***

### **Usage**

**Usage** is the result of aggregating events for a meter over a specific time window.\
Usage is what appears on the invoice for each customer.

***

### **How It All Connects**

Below is a diagram showing the relationship between events, meters, usage, and invoices:

```mermaid theme={null}
flowchart LR
    subgraph Customer Activity
        E1[Event 1]
        E2[Event 2]
        E3[Event 3]
    end
    E1 --> M(Meter)
    E2 --> M
    E3 --> M
    M --> U[Usage]
    U --> I[Invoice]
    style M fill:#e0f7fa,stroke:#0074BA,stroke-width:2px
    style U fill:#fff3e0,stroke:#0074BA,stroke-width:2px
    style I fill:#e8f5e9,stroke:#0074BA,stroke-width:2px
```

* **Events** are raw activity logs.
* **Meters** aggregate events using defined methods, windows, and filters.
* **Usage** is the aggregated value for a customer and period.
* **Invoices** are generated based on usage.

***

## Summary Table

| Concept | What it is                      | Example                |
| ------- | ------------------------------- | ---------------------- |
| Event   | Individual activity record      | User login, API call   |
| Meter   | Aggregates events over a period | "Monthly Active Users" |
| Usage   | Aggregated value for billing    | 500 logins in May 2025 |
| Invoice | Bill sent to customer           | \$50 for 500 logins    |

***

> **Tip:**\
> Events, meters, and usage are the foundation of usage-based billing in Enso.\
> Understanding their relationship is key to accurate and flexible billing.

***