## List With Groups

`client.v1.usage.listWithGroups(UsageListWithGroupsParamsparams, RequestOptionsoptions?): CursorPage<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

- **params:** `UsageListWithGroupsParams`

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

    Body param:

  - **customer\_id:** `string`

    Body param:

  - **window\_size:** `"HOUR" | "DAY" | "NONE"`

    Body param: 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:** `number`

    Query param: Max number of results that should be returned

  - **next\_page:** `string`

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

  - **current\_period:** `boolean`

    Body param: 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:** `string`

    Body param:

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

    Body param:

    - **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. Omit this if you'd like all values for the key returned.

  - **starting\_on:** `string`

    Body param:

### Returns

- `UsageListWithGroupsResponse`
  - **ending\_before:** `string`

  - **group\_key:** `string | null`

  - **group\_value:** `string | null`

  - **starting\_on:** `string`

  - **value:** `number | null`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const usageListWithGroupsResponse of client.v1.usage.listWithGroups({
  billable_metric_id: '222796fd-d29c-429e-89b2-549fabda4ed6',
  customer_id: '04ca7e72-4229-4a6e-ab11-9f7376fccbcb',
  window_size: 'day',
  ending_before: '2021-01-03T00:00:00Z',
  group_by: { key: 'region', values: ['US-East', 'US-West', 'EU-Central'] },
  starting_on: '2021-01-01T00:00:00Z',
})) {
  console.log(usageListWithGroupsResponse.ending_before);
}
```