## List

`v1.usage.list(**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:** `Time`

- **starting\_on:** `Time`

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

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

- **billable\_metrics:** `Array[{ id, group_by}]`

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

  - **id:** `String`

  - **group\_by:** `{ key, values}`

    - **key:** `String`

      The name of the group_by key to use

    - **values:** `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\_ids:** `Array[String]`

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

### Returns

- `class UsageListResponse`

  - **data:** `Array[{ billable_metric_id, billable_metric_name, customer_id, 4 more}]`

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

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

    - **customer\_id:** `String`

    - **end\_timestamp:** `Time`

    - **start\_timestamp:** `Time`

    - **value:** `Float`

    - **groups:** `Hash[Symbol, Float]`

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

  - **next\_page:** `String`

### Example

```ruby
require "metronome_sdk"

metronome = MetronomeSDK::Client.new(bearer_token: "My Bearer Token")

usages = metronome.v1.usage.list(
  ending_before: "2021-01-03T00:00:00Z",
  starting_on: "2021-01-01T00:00:00Z",
  window_size: :HOUR
)

puts(usages)
```