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

List

API Reference
V1
Usage
Get batched usage data
v1.usage.list(UsageListParams**kwargs) -> datalistnext_pagestrUsageListResponse
post/v1/usage

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

Parameters
ending_beforeunion
Union[str, datetime]
formatdate-time
starting_onunion
Union[str, datetime]
formatdate-time
window_sizeliteral
Literal["HOUR", "DAY", "NONE"]

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_pagestr
optional

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

billable_metricsiterable
optional
idstrgroup_byBillableMetricGroupByIterable[BillableMetric]

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

Hide ParametersShow Parameters
idstr
formatuuid
group_bykeystrvalueslistBillableMetricGroupBy
optional
Hide ParametersShow Parameters
keystr

The name of the group_by key to use

valueslist
optional
List[str]

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_idslist
optional
List[str]

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

Returns
UsageListResponseclass
Hide ParametersShow Parameters
datalist
List[Data]
Hide ParametersShow Parameters
billable_metric_idstr
formatuuid
billable_metric_namestr
customer_idstr
formatuuid
end_timestampdatetime
formatdate-time
start_timestampdatetime
formatdate-time
valuefloat
groupsDict[str, Optional[float]]
optional
Optional[Dict[str, Optional[float]]]

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

next_pagestr
from datetime import datetime
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
usages = client.v1.usage.list(
    ending_before=datetime.fromisoformat("2021-01-03T00:00:00"),
    starting_on=datetime.fromisoformat("2021-01-01T00:00:00"),
    window_size="day",
)
print(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"
}