Understand Streams, Meters, and Segments

Understand how streams, meters, and segments work together in Maxio Metering to calculate usage for usage-based billing. These Metering objects define incoming usage events, calculate usage totals, group usage by attributes, and connect measured activity to invoice charges.

How to: 

• To create these objects for the first time, see Get Started with Maxio Metering. 
• To review configuration fields, see Configure Metering.

Stream

A stream defines the structure of the events your system sends to Maxio.

Every stream includes:

• Name and API handle: The API handle is used in the endpoint URL where your system sends events.
• Subscription identifier: Tells Maxio which subscription each event belongs to.
• Event properties: Defines the fields included in each event.

Define the stream schema before sending event data. Maxio validates incoming events against the stream schema.

Example: An API Usage Stream may include api_calls, region, and customer_tier as event properties.

Meter

A meter reads events from a stream and calculates usage.

A meter defines:

• Which stream to read
• Which aggregation type to use
• Which property to calculate, if applicable
• Whether usage is segmented

A stream can have multiple meters. For example, one stream can support one meter that counts API calls and another meter that sums bytes transferred.

For guidance on aggregation types, see Aggregation Types Explained.

Segment

A segment groups usage by a property value. Use segments when usage needs separate calculation or pricing by attribute.

A meter supports up to 10 segment properties simultaneously, enabling granular usage splits by dimensions such as region, model tier, API key, plan type, and environment.

Common segment examples include:

• Region

• Customer tier

• Feature type

• Environment

• API key

• Plan type

Example: If events include a region property, a meter can calculate usage separately for us-east, eu-west, and ap-southeast.

For component pricing by segment, see Design Your Catalog: Using Metering with Components.

How the objects work together

Metering objects work together in this order:

Stream → Meter (with optional segmentation) → Metered Component → Invoice

1. A stream receives events from your system and validates them against the stream schema.
2. A meter optionally groups usage by segment properties, calculating usage separately per segment value. Segment configuration is part of the meter definition, not a separate step.
3. A segment optionally groups the calculated usage by a string property, such as region, customer tier, or environment.
4. A metered component connects the calculated usage to pricing in Advanced Billing.
5. Maxio applies the usage charge to the subscription invoice.

Example setup:

Use the following setup to bill API calls by region:

• Stream: API Usage Stream
• Meter property: api_calls
• Aggregation type: Sum
• Segment: region
• Component pricing: Different price for each region

Key rules:

• Create the stream before sending events.
• Events must match the stream schema.
• Numeric properties can be used for calculations.
• Properties of any supported data type can be used for segments.
• A meter must be connected to a metered component before it creates billing charges.