## List

`v1.usage.list(UsageListParams**kwargs)  -> UsageListResponse`

**post** `/v1/usage`

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

### Parameters

- **ending\_before:** `Union[str, datetime]`

- **starting\_on:** `Union[str, datetime]`

- **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"`

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

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

- **billable\_metrics:** `Iterable[BillableMetric]`

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

  - **id:** `str`

  - **group\_by:** `BillableMetricGroupBy`

    - **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. If this field is omitted, all available values will be returned, up to a maximum of 200.

- **customer\_ids:** `List[str]`

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

### Returns

- `class UsageListResponse`

  - **data:** `List[Data]`

    - **billable\_metric\_id:** `str`

    - **billable\_metric\_name:** `str`

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

    - **end\_timestamp:** `datetime`

    - **start\_timestamp:** `datetime`

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

    - **groups:** `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\_page:** `Optional[str]`

### Example

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