# Usage

## 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);
```

## Ingest

`client.v1.usage.ingest(UsageIngestParamsbody?, RequestOptionsoptions?): void`

**post** `/v1/ingest`

Send usage events to Metronome. The body of this request is expected to be a JSON array of between 1 and 100 usage events. Compressed request bodies are supported with a `Content-Encoding: gzip` header. See [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to learn more about usage events.

### Parameters

- **body:** `UsageIngestParams`

  - **usage:** `Array<Usage>`

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

    - **event\_type:** `string`

    - **timestamp:** `string`

      RFC 3339 formatted

    - **transaction\_id:** `string`

    - **properties:** `Record<string, unknown>`

### Example

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

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

await client.v1.usage.ingest([
  {
    customer_id: 'team@example.com',
    event_type: 'heartbeat',
    timestamp: '2021-01-01T00:00:00Z',
    transaction_id: '2021-01-01T00:00:00Z_cluster42',
  },
]);
```

## 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);
}
```

## Search

`client.v1.usage.search(UsageSearchParamsbody, RequestOptionsoptions?): UsageSearchResponse`

**post** `/v1/events/search`

For a set of events, look up matched billable metrics and customers by transaction id. This endpoint looks at transactions that occurred in the last 34 days, and is intended for sampling-based testing workflows. It is heavily rate limited.

### Parameters

- **body:** `UsageSearchParams`

  - **transactionIds:** `Array<string>`

    The transaction IDs of the events to retrieve

### Returns

- **UsageSearchResponse:** `Array<UsageSearchResponseItem>`

  - **id:** `string`

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

    The ID of the customer in the ingest event body

  - **event\_type:** `string`

  - **timestamp:** `string`

  - **transaction\_id:** `string`

  - **is\_duplicate:** `boolean`

  - **matched\_billable\_metrics:** `Array<MatchedBillableMetric>`

    - **id:** `string`

    - **name:** `string`

    - **aggregate:** `string`

      (DEPRECATED) use aggregation_type instead

    - **aggregate\_keys:** `Array<string>`

      (DEPRECATED) use aggregation_key instead

    - **aggregation\_key:** `string`

      A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is 'count'.

    - **aggregation\_type:** `"COUNT" | "LATEST" | "MAX" | 2 more`

      Specifies the type of aggregation performed on matching events.

      - `"COUNT"`

      - `"LATEST"`

      - `"MAX"`

      - `"SUM"`

      - `"UNIQUE"`

    - **archived\_at:** `string`

      RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.

    - **custom\_fields:** `Record<string, string>`

    - **event\_type\_filter:** `EventTypeFilter`

      An optional filtering rule to match the 'event_type' property of an event.

    - **filter:** `Record<string, unknown>`

      (DEPRECATED) use property_filters & event_type_filter instead

    - **group\_by:** `Array<string>`

      (DEPRECATED) use group_keys instead

    - **group\_keys:** `Array<Array<string>>`

      Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.

    - **property\_filters:** `Array<PropertyFilter>`

      A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.

      - **name:** `string`

        The name of the event property.

      - **exists:** `boolean`

        Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.

      - **in\_values:** `Array<string>`

        Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.

      - **not\_in\_values:** `Array<string>`

        Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.

    - **sql:** `string`

      The SQL query associated with the billable metric

  - **matched\_customer:** `MatchedCustomer`

    The customer the event was matched to if a match was found

    - **id:** `string`

    - **name:** `string`

  - **processed\_at:** `string`

  - **properties:** `Record<string, unknown>`

### Example

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

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

const response = await client.v1.usage.search({ transactionIds: ['2021-01-01T00:00:00Z_cluster42'] });

console.log(response);
```