Metered features

A metered feature object represents two things:

the feature whose entitlement is consumed based on measured usage.
the configuration that measures that usage.

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 Metered featureJSON

Metered features attributes

required, string, max chars=50

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

name

optional, string, max chars=50

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

description

optional, string, max chars=250

A brief description of the metered feature.

type

optional, enumerated string

The type of meter. Determines how usage is measured for the metered feature.

Enum Values

simple

Usage is computed from a 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 metered feature.

Enum Values

active

The metered feature is active and new entitlements and subscription entitlements can be created for it.

archived

No new entitlements and subscription entitlements can be created for the metered feature. However, any pre-existing entitlements and subscription entitlements remain effective.

deleted

The metered feature has been permanently deleted.

query

optional, string, max chars=1000

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.

Usage reporting and subscription billing

For a metered feature whose query includes a GROUP BY clause, grouped usage is available in Retrieve usage summary for a subscription and Retrieve usages for an invoice as PDF. These groups are for reporting only. Subscription billing uses the overall aggregate for the metered feature and does not bill each group separately.

For example, a SUM query can return 60 hours for region=us-east and 40 hours for region=eu-west. The reporting operations can display both groups. Subscription billing uses the overall aggregate of 100 hours.

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 metered feature's query.

features

The feature associated with this metered feature. This array has only one element since any given metered feature 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 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 active. 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 entitlements and subscription entitlements 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 API Calls, the unit can be request.

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. The value is always true.

levels

An ordered list of entitlement levels available for the feature.