Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Entitlements
Customers

Get customer entitlement history

Returns historical balance and usage data for the entitlement. The queried history can span accross multiple reset events.

BurndownHistory returns a continous history of segments, where the segments are seperated by events that changed either the grant burndown priority or the usage period.

WindowedHistory returns windowed usage data for the period enriched with balance information and the list of grants that were being burnt down in that window.

get/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/history

Path parameters

string required

ULID (Universally Unique Lexicographically Sortable Identifier).

OR
string required

ExternalKey is a looser version of key.

Example:01G65Z755AFWAKHE12NY0CQ9FH
entitlementIdOrFeatureKeystring required

Query parameters

fromstring date-time
Example:2023-01-01T01:01:01.001Z

Start of time range to query entitlement: date-time in RFC 3339 format. Defaults to the last reset. Gets truncated to the granularity of the underlying meter.

tostring date-time
Example:2023-01-01T01:01:01.001Z

End of time range to query entitlement: date-time in RFC 3339 format. Defaults to now. If not now then gets truncated to the granularity of the underlying meter.

windowSize'MINUTE' | 'HOUR' | 'DAY' | 'MONTH' required

Aggregation window size.

Windowsize

windowTimeZonestring

The timezone used when calculating the windows.

Response

The request has succeeded.

Example response

{
  "windowedHistory": [
    {
      "period": {
        "from": "2023-01-01T01:01:01.001Z",
        "to": "2023-02-01T01:01:01.001Z"
      },
      "usage": 100,
      "balanceAtStart": 100
    }
  ],
  "burndownHistory": [
    {
      "period": {
        "from": "2023-01-01T01:01:01.001Z",
        "to": "2023-02-01T01:01:01.001Z"
      },
      "usage": 100,
      "overage": 100,
      "balanceAtStart": 100,
      "grantBalancesAtStart": {
        "01G65Z755AFWAKHE12NY0CQ9FH": 100
      },
      "balanceAtEnd": 100,
      "grantBalancesAtEnd": {
        "01G65Z755AFWAKHE12NY0CQ9FH": 100
      },
      "grantUsages": [
        {
          "grantId": "01G65Z755AFWAKHE12NY0CQ9FH",
          "usage": 100
        }
      ]
    }
  ]
}