Usage

Endpointhttps://api.kontorion.eu/v1

List usage events

GET

https://api.kontorion.eu/v1

/usage

Returns paginated raw usage events for the org, newest first. All filter params AND together; multi-value metric_key is repeatable or comma-separated. Cursor is opaque (timestamp + id) - pass the previous response's pagination.cursor to load the next page. Page size defaults to 25, max 100.

List usage events › query Parameters

limit

integer

Page size (default 25, max 100)

cursor

string

Pagination cursor

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string[] · explode: true

Filter by metric key. Repeatable or comma-separated.

occurred_after

string

Filter by timestamp >= value (RFC3339)

occurred_before

string

Filter by timestamp < value (RFC3339)

List usage events › Responses

Paginated list with data and pagination envelope

object[]

customer_id

string

object

external_cost_amount

number

external_cost_currency

string

id

string

idempotency_key

string

ingested_at

string

object

metric_key

string

organization_id

string

price_key

string

object

product_id

string

quantity

number

subscription_id

string

timestamp

string

wallet_currency

string

WalletCurrency, when non-nil, pins the event to a specific wallet at finalize time: the meter evaluator groups by this column and the resulting invoice routes to wallet (customer_id, *WalletCurrency). NULL falls back to the customer's preferred-currency cascade — identical to pre-040 behaviour, so legacy events keep working.

GET/usage

curl --request GET \
  --url https://api.kontorion.eu/v1/usage

shell

Example Responses

{
  "key": [
    {
      "customer_id": "customer_id",
      "dimension_vars": {
        "key": "string"
      },
      "external_cost_amount": 0,
      "external_cost_currency": "external_cost_currency",
      "id": "id",
      "idempotency_key": "idempotency_key",
      "ingested_at": "ingested_at",
      "metadata": {
        "key": {}
      },
      "metric_key": "metric_key",
      "organization_id": "organization_id",
      "price_key": "price_key",
      "pricing_vars": {
        "key": 0
      },
      "product_id": "product_id",
      "quantity": 0,
      "subscription_id": "subscription_id",
      "timestamp": "timestamp",
      "wallet_currency": "wallet_currency"
    }
  ]
}

json

application/json

Time-bucketed usage aggregate

GET

https://api.kontorion.eu/v1

/usage/aggregate

Server-side aggregation over the usage_events hypertable. Replaces the chart UI's old client-side bucketing so totals are accurate regardless of event volume. Caps the window at MaxAggregateBuckets at the requested resolution.

Time-bucketed usage aggregate › query Parameters

bucket

string · required

Bucket size: hour | day | week

since

string · required

Window lower bound (RFC3339)

until

string

Window upper bound (RFC3339); defaults to now

metric

string

Metric: count (default) | sum_quantity

group_by

string

Grouping: none (default) | metric_key | dim:

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string[] · explode: true

Filter by metric_key. Repeatable or comma-separated.

top

integer

Truncate to top-N series, fold the rest into 'Other' (default 8; 0 disables)

Time-bucketed usage aggregate › Responses

bucket

string · enum

Enum values:

hour

day

week

group_by

string

metric

string · enum

Enum values:

count

sum_quantity

object[]

series

string[]

since

string

until

string

Transactions Users

List usage events

GET

https://api.kontorion.eu/v1

/usage

List usage events › query Parameters

limit

integer

Page size (default 25, max 100)

cursor

string

Pagination cursor

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string[] · explode: true

Filter by metric key. Repeatable or comma-separated.

occurred_after

string

Filter by timestamp >= value (RFC3339)

occurred_before

string

Filter by timestamp < value (RFC3339)

List usage events › Responses

Paginated list with data and pagination envelope

object[]

customer_id

string

object

external_cost_amount

number

external_cost_currency

string

id

string

idempotency_key

string

ingested_at

string

object

metric_key

string

organization_id

string

price_key

string

object

product_id

string

quantity

number

subscription_id

string

timestamp

string

wallet_currency

string

Time-bucketed usage aggregate

GET

https://api.kontorion.eu/v1

/usage/aggregate

Time-bucketed usage aggregate › query Parameters

bucket

string · required

Bucket size: hour | day | week

since

string · required

Window lower bound (RFC3339)

until

string

Window upper bound (RFC3339); defaults to now

metric

string

Metric: count (default) | sum_quantity

group_by

string

Grouping: none (default) | metric_key | dim:

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string[] · explode: true

Filter by metric_key. Repeatable or comma-separated.

top

integer

Truncate to top-N series, fold the rest into 'Other' (default 8; 0 disables)

Time-bucketed usage aggregate › Responses

bucket

string · enum

Enum values:

hour

day

week

group_by

string

metric

string · enum

Enum values:

count

sum_quantity

object[]

series

string[]

since

string

until

string