Skip to main content
A usage chart that only splits by feature cannot answer the questions customers actually ask: which region is driving the bill, which model costs the most, which instance spiked last week. With usage properties turned on, customers can group and filter usage by event property on the hosted portal’s Usage tab. The same controls are available through the portal analytics API for a front end you build. The feature is off by default. You turn it on per environment and choose which properties customers can see.

Using property controls

On the Usage tab, use the filter bar to narrow usage by feature or property value. In Usage breakdown, use Group by to choose a property. A front end you build can use the corresponding request fields: To drill down, combine the two: filter region to us-east-1 and group by instance_id. Grouping is available when the server returns visible property keys for the customer and date range. A property’s filter appears when values are available for it.
  • The breakdown groups property values by cost, highest first. Expand a group to see its features, usage and cost.
  • Usage without the property appears under No value.
  • Grouping changes the breakdown, not the trend chart. The chart and metric cards respect the active feature and property filters. Cost and margin cards appear only when enabled in the portal configuration.

Turning it on

In the dashboard, open Settings → Customer experience → Portal. Keep the Usage section visible, then under Usage properties, turn on Customers can group their usage by event property. Optionally enter comma-separated keys in Only these keys and Never these keys, then click Save changes. Reload the customer’s portal to use the controls. Alternatively, write analytics_config into the customer_portal_config setting through the settings API. Both methods configure the hosted portal and its analytics endpoints:
The write replaces analytics_config as a whole and leaves the rest of the setting, such as your sections and theme, as it is. Send all three fields every time, because a field you leave out is cleared. Settings writes require Super Admin. Through the API, use a Super Admin user’s API key; a service account key is refused. The portal panel edits the same setting, and Reset to defaults deletes it. To find property names for the lists, call POST /v1/meter-usage/properties with your API key. See API.
A property in both lists is hiddenhidden_keys always wins over allowed_keys.

Which properties customers can use

A property is available to customers only when all of these hold:
  • The feature is turned on, and the property passes your show and hide lists.
  • It is not an aggregation property. Properties a meter aggregates on are always hidden: the field of a SUM, MAX, AVG, LATEST or SUM_WITH_MULTIPLIER meter, and any property used in a meter’s expression. This applies across every meter on the same event. The fields of COUNT and COUNT_UNIQUE meters are identifiers, not quantities, so they stay available.
  • Its name uses only letters, numbers, _ and .
Send property values as strings to group or filter by themGrouping and filtering read property values as strings. A property sent as a number, such as "version": 2, groups as if the property were missing and matches no filter. Send "version": "2" instead.
The properties endpoint builds its list from the customer’s most recent usage of each meter in the requested date range. A property that only appears on older events may not be listed.

API

A portal front end calls these endpoints with the customer’s session token. Request bodies take start_time, end_time and optional feature_ids.
A property the customer cannot use returns 400 with property key "<key>" is not available. The same lookups exist for your own API key at /v1/meter-usage/properties and /v1/meter-usage/properties/values. They take an external_customer_id and do not apply the show and hide lists, so you can see every property. Without external_customer_id, the properties lookup covers the whole environment.

Limitations

  • Grouping by a property with thousands of values returns every group, which makes the response large and slower to load.
  • After you change the setting, open portal sessions can take up to a minute to reflect it.

Customer Portal

Sessions, sections and the security model

Portal configuration

The full configuration schema and theming

Portal API reference

Every endpoint available to a portal session

Metered features

How meters aggregate event properties