Meters

A meter captures the usage measurement configuration of a metered feature.

Meter configuration examples

The following response excerpts show how query, column_definitions, and group_by represent the metering configuration.

Availability

Support for adding GROUP BY to metered features and retrieving usage grouped by attributes is an upcoming capability and is not generally available yet. It will be made available in the coming weeks.

When query includes a GROUP BY clause, the response includes group_by as an ordered list of the group-by attributes. Their order matches the order in the GROUP BY clause. The group_by attribute is not returned when the query does not include a GROUP BY clause.

Without group-by attributes

With group-by attributes

Group-by attributes used only in the GROUP BY clause are returned in group_by and do not require column_definitions entries.

Sample MeterJSON

Meters attributes

required, string, max chars=50

A unique identifier for the meter. This is the same as feature.id.

name

required, string, max chars=50

A case-sensitive name for the meter. For example: API Calls, Input Tokens.

description

optional, string, max chars=500

A brief description of the meter.

type

required, enumerated string

The type of meter that determines how usage is measured for the meter.

Enum Values

simple

Usage is computed from the SQL query over usage_event properties.

compound

Usage is computed from a mathematical formula combining other meters.

status

optional, enumerated string

The current status of the meter.

Enum Values

active

The meter is active and new entitlements can be created towards it.

archived

No new entitlements can be created towards the meter. However, any pre-existing entitlements from the time that the meter was active remain effective.

deleted

The meter has been permanently deleted.

query

required, string, max chars=500

The SQL query used to calculate usage from usage_event properties. For example: SELECT SUM(api_calls) FROM events WHERE status = 'completed'.

To group usage by attribute values, include a GROUP BY clause. Each distinct set of group-by attribute values forms a separate usage group. For example: SELECT SUM(hours) FROM events WHERE status = 'completed' GROUP BY gpu_type, region. The response returns the group-by attribute names in group_by, in the same order.

Availability

Constraints

Properties used in the aggregate expression or WHERE clause must be listed in column_definitions.column_name.
A group-by attribute used only in the GROUP BY clause does not require a column_definitions entry. Its value is treated as a string.
The GROUP BY clause can contain up to 5 group-by attributes.
Exact duplicate group-by attribute names are not allowed. Names are case-sensitive, so region, region is invalid, while region, Region identifies two different attributes.

created_at

required, timestamp(UTC) in seconds

When the meter was created.

updated_at

optional, timestamp(UTC) in seconds

When the meter was last updated.

group_by

optional, string, max chars=100

An ordered list of the group-by attributes in the GROUP BY clause of query. This attribute is returned only when query includes a GROUP BY clause.

Availability

For example, when query is SELECT SUM(hours) FROM events WHERE status = 'completed' GROUP BY gpu_type, region, group_by is ["gpu_type", "region"].

column_definitions

Definitions of the columns or properties referenced by the meter's query. Each entry describes one column used to measure usage.

features

The feature associated with this meter. This array has only one element since any given meter is associated with only one feature.

Column definition attributes

column_name

required, string, max chars=100

Name of the column or property used in the query. For example, request_count or input_tokens.

data_type

required, enumerated string

Data type of the column or property.

Enum Values

number

The column or property holds a numeric value.

string

The column or property holds a string value.

Feature attributes

required, string, max chars=50

A unique and immutable identifier for the feature. This is the same as meter.id.

name

required, string, max chars=50

A case-sensitive unique name for the feature.

description

optional, string, max chars=500

A brief description of the feature.

status

optional, enumerated string

The current status of the feature.

Enum Values

active

The feature is published. Any entitlements or subscription entitlements defined for the feature take effect immediately.

archived

No new entitlements or subscription entitlements can be created for the feature. However, any pre-existing item or subscription entitlements from the time that the feature was active remain effective.

draft

This value is not applicable for metered features.

type

optional, enumerated string

The type of feature. The value is always range.

Enum Values

switch

This value is not applicable for metered features.

custom

This value is not applicable for metered features.

quantity

This value is not applicable for metered features.

range

The feature is quantity based, with entitlement levels between 1 and unlimited.

unit

optional, string, max chars=50

Specifies the unit of measure. The value is expected in the singular form. It is pluralized automatically as needed. For example, for a feature such as user licenses, the unit can be license.

resource_version

optional, long

The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

updated_at

optional, timestamp(UTC) in seconds

When the feature was last updated.

created_at

required, timestamp(UTC) in seconds

When the feature was created.

metered

required, boolean

Indicates whether the feature is metered. Always true.

levels

An ordered list of entitlement levels available for the feature.