## List

`client.v1.usage.list(UsageListParamsparams, RequestOptionsoptions?): UsageListResponse`

**post** `/v1/usage`

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

### Parameters

- **params:** `UsageListParams`

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

    Body param:

  - **starting\_on:** `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"`

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

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

  - **billable\_metrics:** `Array<BillableMetric>`

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

    - **id:** `string`

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

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

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

### Returns

- `UsageListResponse`
  - **data:** `Array<Data>`

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

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

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

    - **end\_timestamp:** `string`

    - **start\_timestamp:** `string`

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

    - **groups:** `Record<string, number | null>`

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

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

### Example

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

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

const usages = await client.v1.usage.list({
  ending_before: '2021-01-03T00:00:00Z',
  starting_on: '2021-01-01T00:00:00Z',
  window_size: 'day',
});

console.log(usages.data);
```