Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

List With Groups

API Reference
V1
Usage
Get usage data with paginated groupings
client.v1.usage.listWithGroups(UsageListWithGroupsParamsparams, RequestOptionsoptions?): CursorPage<ending_beforestringgroup_keyuniongroup_valueunionstarting_onstringvalueunionUsageListWithGroupsResponse>
post/v1/usage/groups

Fetch aggregated usage data for the specified customer, billable-metric, and optional group, broken into intervals of the specified length.

Parameters
paramsbillable_metric_idstringcustomer_idstringwindow_sizeunionlimitnumbernext_pagestringcurrent_periodbooleanending_beforestringgroup_byGroupBystarting_onstringUsageListWithGroupsParams
Hide ParametersShow Parameters
billable_metric_idstring

Body param:

formatuuid
customer_idstring

Body param:

formatuuid
window_sizeunion
"HOUR" | "DAY" | "NONE"

Body param: A window_size of "day" or "hour" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of "none" will return a single usage aggregate for the entirety of the specified period.

Hide ParametersShow Parameters
"HOUR"
"DAY"
"NONE"
limitnumber
optional

Query param: Max number of results that should be returned

minimum1
maximum100
next_pagestring
optional

Query param: Cursor that indicates where the next page of results should start.

current_periodboolean
optional

Body param: If true, will return the usage for the current billing period. Will return an error if the customer is currently uncontracted or starting_on and ending_before are specified when this is true.

ending_beforestring
optional

Body param:

formatdate-time
group_byGroupBy
optional

Body param:

Hide ParametersShow Parameters
keystring

The name of the group_by key to use

valuesarray
optional
Array<string>

Values of the group_by key to return in the query. Omit this if you'd like all values for the key returned.

starting_onstring
optional

Body param:

formatdate-time
Returns
UsageListWithGroupsResponse
Hide ParametersShow Parameters
ending_beforestring
formatdate-time
group_keyunion
string | null
group_valueunion
string | null
starting_onstring
formatdate-time
valueunion
number | null
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const usageListWithGroupsResponse of client.v1.usage.listWithGroups({
  billable_metric_id: '222796fd-d29c-429e-89b2-549fabda4ed6',
  customer_id: '04ca7e72-4229-4a6e-ab11-9f7376fccbcb',
  window_size: 'day',
  ending_before: '2021-01-03T00:00:00Z',
  group_by: { key: 'region', values: ['US-East', 'US-West', 'EU-Central'] },
  starting_on: '2021-01-01T00:00:00Z',
})) {
  console.log(usageListWithGroupsResponse.ending_before);
}
200 Example
{
  "data": [
    {
      "ending_before": "2019-12-27T18:11:19.117Z",
      "group_key": "group_key",
      "group_value": "group_value",
      "starting_on": "2019-12-27T18:11:19.117Z",
      "value": 0
    }
  ],
  "next_page": "next_page"
}