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

List

API Reference
V1
Usage
Get batched usage data
client.v1.usage.list(UsageListParamsparams, RequestOptionsoptions?): dataarraynext_pageunionUsageListResponse
post/v1/usage

Fetch aggregated usage data for multiple customers and billable-metrics, broken into intervals of the specified length.

Parameters
paramsending_beforestringstarting_onstringwindow_sizeunionnext_pagestringbillable_metricsarraycustomer_idsarrayUsageListParams
Hide ParametersShow Parameters
ending_beforestring

Body param:

formatdate-time
starting_onstring

Body param:

formatdate-time
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"
next_pagestring
optional

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

billable_metricsarray
optional
Array<BillableMetric>

Body param: A list of billable metrics to fetch usage for. If absent, all billable metrics will be returned.

Hide ParametersShow Parameters
idstring
formatuuid
group_bykeystringvaluesarrayGroupBy
optional
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. If this field is omitted, all available values will be returned, up to a maximum of 200.

customer_idsarray
optional
Array<string>

Body param: A list of Metronome customer IDs to fetch usage for. If absent, usage for all customers will be returned.

Returns
UsageListResponse
Hide ParametersShow Parameters
dataarray
Array<Data>
Hide ParametersShow Parameters
billable_metric_idstring
formatuuid
billable_metric_namestring
customer_idstring
formatuuid
end_timestampstring
formatdate-time
start_timestampstring
formatdate-time
valueunion
number | null
groupsRecord<string, number | null>
optional

Values will be either a number or null. Null indicates that there were no matches for the group_by value.

next_pageunion
string | null
import Metronome from '@metronome/sdk';

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

const usages = await client.v1.usage.list({
  ending_before: '2021-01-03T00:00:00Z',
  starting_on: '2021-01-01T00:00:00Z',
  window_size: 'day',
});

console.log(usages.data);
200 Example
{
  "data": [
    {
      "billable_metric_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "billable_metric_name": "billable_metric_name",
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "end_timestamp": "2019-12-27T18:11:19.117Z",
      "start_timestamp": "2019-12-27T18:11:19.117Z",
      "value": 0,
      "groups": {
        "foo": 0
      }
    }
  ],
  "next_page": "next_page"
}