---
title: "Get customer entitlement history"
method: GET
path: "/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/history"
tags: ["Entitlements", "Customers"]
---

# Get customer entitlement history

`GET /api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/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.

## Path parameters

- `customerIdOrKey` union, required — ULID (Universally Unique Lexicographically Sortable Identifier) or external unique key.
  - string — ULID (Universally Unique Lexicographically Sortable Identifier).
  - string — ExternalKey is a looser version of key.
- `entitlementIdOrFeatureKey` string, required

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `windowSize` 'MINUTE' | 'HOUR' | 'DAY' | 'MONTH', required — Aggregation window size.
- `windowTimeZone` string

## Response `200`

The request has succeeded.

- WindowedBalanceHistory — The windowed balance history.
  - `burndownHistory` GrantBurnDownHistorySegment[], required — Grant burndown history.
    - `balanceAtEnd` number, double, required — The entitlement balance at the end of the period.
    - `balanceAtStart` number, double, required — entitlement balance at the start of the period.
    - `grantBalancesAtEnd` object, required — The balance breakdown of each active grant at the end of the period: GrantID: Balance
    - `grantBalancesAtStart` object, required — The balance breakdown of each active grant at the start of the period: GrantID: Balance
    - `grantUsages` GrantUsageRecord[], required — Which grants were actually burnt down in the period and by what amount.
      - `grantId` string, required — The id of the grant
      - `usage` number, double, required — The usage in the period
    - `overage` number, double, required — Overuse that wasn't covered by grants.
    - `period` Period, required — A period with a start and end time.
      - `from` string, date-time, required — Period start time.
      - `to` string, date-time, required — Period end time.
    - `usage` number, double, required — The total usage of the grant in the period.
  - `windowedHistory` BalanceHistoryWindow[], required — The windowed balance history. - It only returns rows for windows where there was usage. - The windows are inclusive at their start and exclusive at their end. - The last window may be smaller than the window size and is inclusive at both ends.
    - `balanceAtStart` number, double, required — The entitlement balance at the start of the period.
    - `period` Period, required — A period with a start and end time.
      - `from` string, date-time, required — Period start time.
      - `to` string, date-time, required — Period end time.
    - `usage` number, double, required — The total usage of the feature in the period.

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — The request has not been applied because it lacks valid authentication credentials for the target resource.
- `403` — The server understood the request but refuses to authorize it.
- `404` — The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
- `412` — One or more conditions given in the request header fields evaluated to false when tested on the server.
- `500` — The server encountered an unexpected condition that prevented it from fulfilling the request.
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
- `default` — An unexpected error response.

---

[API](https://skmtc.dev/openmeter/apis/openmeter-cloud-api.md) · [All operations](https://skmtc.dev/openmeter/apis/openmeter-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeter/openmeter-cloud-api/revisions/c9c0ec9cffe9/schema)