OpenMeter Entitlements

Get customer entitlement history

Changed on

Pre-release Endpoint This endpoint is currently in beta and is subject to change.

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/v3/openmeter/customers/{customerId}/entitlements/{entitlementId}/history

Request

  • Base URL: https://global.api.konghq.com
  • URL: https://global.api.konghq.com/v3/openmeter/customers/{customerId}/entitlements/{entitlementId}/history
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

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"
      },
      "usage": "100",
      "balance_at_start": "100"
    }
  ],
  "burndown_history": [
    {
      "period": {
        "from": "2023-01-01T01:01:01.001Z",
        "to": "2023-01-01T01:01:01.001Z"
      },
      "usage": "100",
      "overage": "0",
      "balance": {
        "start": "100",
        "end": "50"
      },
      "grant_balances": {
        "start": {
          "01G65Z755AFWAKHE12NY0CQ9FH": "100"
        },
        "end": {
          "01G65Z755AFWAKHE12NY0CQ9FH": "50"
        }
      },
      "grant_usages": [
        {
          "grant_id": "01G65Z755AFWAKHE12NY0CQ9FH",
          "usage": "50"
        }
      ]
    }
  ]
}

Changes

  • 7aab863a6daaRevision changes
    • breaking

      added to the / response property oneOf list for the response status

    • warning

      added the new key_invalid enum value to the ////// response property for the response status

    • warning

      added the new unique enum value to the ////// response property for the response status

  • 59663dd13a10Revision changes
    • info

      endpoint added