## List With Groups

`v1.usage.list_with_groups(UsageListWithGroupsParams**kwargs)  -> SyncCursorPage[UsageListWithGroupsResponse]`

**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\_id:** `str`

- **customer\_id:** `str`

- **window\_size:** `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.

  - `"HOUR"`

  - `"DAY"`

  - `"NONE"`

- **limit:** `int`

  Max number of results that should be returned

- **next\_page:** `str`

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

- **current\_period:** `bool`

  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\_before:** `Union[str, datetime]`

- **group\_by:** `GroupBy`

  - **key:** `str`

    The name of the group_by key to use

  - **values:** `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\_on:** `Union[str, datetime]`

### Returns

- `class UsageListWithGroupsResponse`

  - **ending\_before:** `datetime`

  - **group\_key:** `Optional[str]`

  - **group\_value:** `Optional[str]`

  - **starting\_on:** `datetime`

  - **value:** `Optional[float]`

### Example

```python
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)
```