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
v1.usage.list_with_groups(UsageListWithGroupsParams**kwargs) -> SyncCursorPage[ending_beforedatetimegroup_keystrgroup_valuestrstarting_ondatetimevaluefloatUsageListWithGroupsResponse]
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
billable_metric_idstr
formatuuid
customer_idstr
formatuuid
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"
limitint
optional

Max number of results that should be returned

minimum1
maximum100
next_pagestr
optional

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

current_periodbool
optional

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_beforeunion
optional
Union[str, datetime]
formatdate-time
group_bykeystrvalueslistGroupBy
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. Omit this if you'd like all values for the key returned.

starting_onunion
optional
Union[str, datetime]
formatdate-time
Returns
UsageListWithGroupsResponseclass
Hide ParametersShow Parameters
ending_beforedatetime
formatdate-time
group_keystr
group_valuestr
starting_ondatetime
formatdate-time
valuefloat
from datetime import datetime
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
page = client.v1.usage.list_with_groups(
    billable_metric_id="222796fd-d29c-429e-89b2-549fabda4ed6",
    customer_id="04ca7e72-4229-4a6e-ab11-9f7376fccbcb",
    window_size="day",
    ending_before=datetime.fromisoformat("2021-01-03T00:00:00"),
    group_by={
        "key": "region",
        "values": ["US-East", "US-West", "EU-Central"],
    },
    starting_on=datetime.fromisoformat("2021-01-01T00:00:00"),
)
page = page.data[0]
print(page.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"
}