Kaiten

List an entitlement's usage reports for an instance

The usage history of one instance and entitlement: every accepted report in the range, with the counter before and after it and the limit in force, in reportSeq order, paged with afterSeq. Decimals are strings. Reports are kept for the organization's usage history retention.

GET
/instances/{instanceSlug}/entitlements/{entitlementSlug}/usage/reports

Authorization

bearerAuth read:instances
AuthorizationBearer <token>

A JWT verified by the proxy in front of this API, or a Kaiten access token (ksh_...) — send either as Authorization: Bearer <token>. The scopes listed on each operation are checked server-side against current stored user assignments or stored service-token permissions, never JWT claims; write:<module> implies read:<module>, and read:* / write:* are wildcards over every module. x-kaiten-scopes lists every scope such a token can carry, including those enforced by a service in front of this API rather than by one of its operations.

In: header

Scope: read:instances

Path Parameters

instanceSlug*string

Instance slug

entitlementSlug*string

Entitlement slug

Query Parameters

from?string

Start of the range, inclusive (RFC 3339). Defaults to 30 days before to, moved up to the start of the organization's usage history when that is later. An explicit from before it answers 422 ListUsageReports.OutsideRetention.

Formatdate-time
to?string

End of the range, exclusive (RFC 3339). Defaults to now.

Formatdate-time
afterSeq?integer

Return the reports after this reportSeq: the nextAfterSeq of the previous page

Formatint64
Range0 <= value
limit?integer

Maximum number of reports to return (default 100, max 500)

Formatint32
Range1 <= value <= 500
transactionId?string

Only the report sent with this idempotency key

Lengthlength <= 128

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://app.kaiten.sh/api/instances/instance-slug/entitlements/entitlement-slug/usage/reports"
{
  "items": [
    {
      "aggregationMethod": "SUM",
      "behavior": "append",
      "delta": "600",
      "entitlementId": "79a605b5-f302-4c5d-bbc7-cbd58f1a9b0d",
      "eventCountAfter": 1,
      "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
      "licenseId": "be894337-ec7c-4bdc-ac72-f939e31237ae",
      "limitValue": "1000",
      "overageDelta": "0",
      "overagePercent": 50,
      "properties": {
        "property1": null,
        "property2": null
      },
      "reportSeq": 42,
      "reportedAt": "2026-10-05T08:00:00.000Z",
      "reportedValue": "600",
      "transactionId": "llm-call-9f2c:tokens",
      "valueAfter": "600",
      "valueBefore": "0",
      "windowEnd": "2019-08-24T14:15:22Z",
      "windowStart": "2019-08-24T14:15:22Z"
    }
  ],
  "nextAfterSeq": 100
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

Report entitlement usage metric for an instance

Report a usage metric for a specific entitlement in a given instance, with optional metadata. The server dates every report on receipt; the request carries no timestamp. Send an Idempotency-Key to make retries safe: without one, a report sent twice counts twice.

Export an entitlement's usage reports for an instance

Streams every report of one instance and entitlement in the range as CSV or NDJSON, in reportSeq order. Decimals are written exactly as the journal stores them.