Sign in
OpenMeter Entitlements

Get customer entitlement history

Changed on

Get the balance and usage history of a metered entitlement. The queried range may span multiple usage periods.

windowed_history groups usage into windows of the requested size and reports the balance at the start of each window. burndown_history lists the periods in which grants were consumed in a fixed order, together with the usage taken from each grant.

get/openmeter/customers/{customerId}/entitlements/{entitlementId}/history

Request

  • Base URL: http://localhost:8888/api/v3
  • URL: http://localhost:8888/api/v3/openmeter/customers/{customerId}/entitlements/{entitlementId}/history
  • Auth: none declared

Path parameters

customerIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH
entitlementIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH

Query parameters

fromstring date-time

RFC3339 formatted date-time string in UTC.

Example:2023-01-01T01:01:01.001Z

The start of the queried range. Defaults to the last reset. Truncated to the minute. The range may span at most 1000 windows.

tostring date-time

RFC3339 formatted date-time string in UTC.

Example:2023-01-01T01:01:01.001Z

The end of the queried range. Defaults to the current time. Truncated to the minute unless it is the current time.

window_size'PT1H' | 'P1D' required

The meter query granularities the usage history can be grouped into. Sub-hour windows are too expensive to compute and monthly windows are not supported.

The size of the windows the usage is grouped into.

time_zonestring

The IANA time zone the windows are aligned to.

Response

EntitlementHistory response.

Example response

{
  "windowed_history": [
    {
      "period": {
        "from": "2023-01-01T01:01:01.001Z",
        "to": "2023-01-01T01:01:01.001Z"
      }
    }
  ],
  "burndown_history": [
    {
      "period": {
        "from": "2023-01-01T01:01:01.001Z",
        "to": "2023-01-01T01:01:01.001Z"
      },
      "grant_balances": {
        "start": {
          "01G65Z755AFWAKHE12NY0CQ9FH": "100"
        },
        "end": {
          "01G65Z755AFWAKHE12NY0CQ9FH": "50"
        }
      },
      "grant_usages": [
        {
          "grant_id": "01G65Z755AFWAKHE12NY0CQ9FH"
        }
      ]
    }
  ]
}

Changes