Usage Query

Endpointhttps://api.kontorion.eu/v1

Query aggregated usage data for a customer's subscription within a time range. Returns the computed metric value (after aggregation) and the underlying event count.

Use this to build usage dashboards, generate real-time consumption alerts, or preview what a customer's next invoice will look like before it's generated.

List usage events

GET

https://api.kontorion.eu/v1

/usage-events

Returns paginated raw usage events for the org, newest first - the read side of POST /usage-events. All filter params AND together; multi-value metric_key is repeatable or comma-separated.

List usage events › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string

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 › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List usage events › Responses

array | null · required

object · required

GET/usage-events

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

shell

Example Responses

{
  "data": [
    {
      "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "dimension_vars": {
        "key": "string"
      },
      "external_cost_amount": "49.5",
      "external_cost_currency": "external_cost_currency",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "idempotency_key": "idempotency_key",
      "ingested_at": "2024-08-25T15:00:00Z",
      "metadata": {
        "key": {}
      },
      "metric_key": "metric_key",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "price_key": "price_key",
      "pricing_vars": {
        "key": "49.5"
      },
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": "49.5",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "timestamp": "2024-08-25T15:00:00Z",
      "wallet_currency": "wallet_currency"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Ingest a usage event (fire-and-forget billing)

POST

https://api.kontorion.eu/v1

/usage-events

Accepts a single usage event or a batch ({"events": [...]}). Records the event for billing on the next invoice; does not check wallet balance, credit limits, or reservation availability. Use the reserve/capture flow (POST /reservations) when up-front fund availability matters. Returns 202 {status: queued} when the event settles a reservation. Read ingested events back at GET /usage-events.

Ingest a usage event (fire-and-forget billing) › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Ingest a usage event (fire-and-forget billing) › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

customer_id

string · uuid

Customer that consumed the metric.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Named dimension values used to select the price tier.

external_cost_amount

string · pattern: ^-?\d+(\.\d+)?$

Caller-supplied wholesale cost (COGS) fed to cost-plus formulas, MAJOR units; requires external_cost_currency.

Example: 49.5

external_cost_currency

string

ISO 4217 currency of external_cost_amount; one currency per (subscription, metric) group.

hold_id

string · uuid

Reserve hold this event captures against; null for direct (non-reserve) ingest.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

idempotency_key

string

Caller key that dedupes replays of the same event; required.

object

Arbitrary caller-supplied key/value annotations carried on the event.

metric_key

string · maxLength: 100

Metric this event records usage for; must match the product's meter binding.

Example: api_calls

price_key

string · maxLength: 100

Price key selecting a tier for keyed products; required when the product exposes keyed prices.

object

Named numeric variables bound into the price formula at finalize time.

product_id

string · uuid

Metered product the event is billed under.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

quantity

string · pattern: ^-?\d+(\.\d+)?$

Number of metric units to record; must be non-negative.

Example: 49.5

subscription_id

string · uuid

Subscription the usage is charged against.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

timestamp

string · date-time

When the usage occurred; omitted or zero stamps the server's ingest time. Set explicitly for backfill/historical imports.

wallet_currency

string

ISO 4217 currency pinning the event to a specific wallet; the wallet must exist for (customer_id, wallet_currency). Null uses the customer's preferred-currency cascade.

Ingest a usage event (fire-and-forget billing) › Responses

Created

required

Outcome-dependent: on 201 the created UsageEvent (single-event body) or the BatchIngestResult (batch body); on 202 the UsageEventQueuedResponse when the event settles a reservation and is processed asynchronously (the hold's state is observable at GET /wallets/{id}/holds).

POST/usage-events

curl --request POST \
  --url https://api.kontorion.eu/v1/usage-events \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": "49.5",
  "external_cost_currency": "external_cost_currency",
  "hold_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "api_calls",
  "price_key": "price_key",
  "pricing_vars": {
    "key": "49.5"
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "quantity": "49.5",
  "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2024-08-25T15:00:00Z",
  "wallet_currency": "wallet_currency"
}
'

shell

Example Request Body

{
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": "49.5",
  "external_cost_currency": "external_cost_currency",
  "hold_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "api_calls",
  "price_key": "price_key",
  "pricing_vars": {
    "key": "49.5"
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "quantity": "49.5",
  "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "timestamp": "2024-08-25T15:00:00Z",
  "wallet_currency": "wallet_currency"
}

json

Example Responses

{
  "data": {
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "dimension_vars": {
      "key": "string"
    },
    "external_cost_amount": "49.5",
    "external_cost_currency": "external_cost_currency",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "idempotency_key": "idempotency_key",
    "ingested_at": "2024-08-25T15:00:00Z",
    "metadata": {
      "key": {}
    },
    "metric_key": "metric_key",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "price_key": "price_key",
    "pricing_vars": {
      "key": "49.5"
    },
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "quantity": "49.5",
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "timestamp": "2024-08-25T15:00:00Z",
    "wallet_currency": "wallet_currency"
  }
}

json

application/json

Time-bucketed usage aggregate

GET

https://api.kontorion.eu/v1

/usage-events/aggregate

Server-side aggregation over the usage_events hypertable. Caps the window at MaxAggregateBuckets at the requested resolution.

Time-bucketed usage aggregate › query Parameters

since

string · required

Window lower bound (RFC3339)

bucket

string

Bucket size: hour | day (default) | week

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

Filter by metric_key. Repeatable or comma-separated

top

string

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

Time-bucketed usage aggregate › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Time-bucketed usage aggregate › Responses

object · required

Pricing/Resolutions Meters

List usage events

GET

https://api.kontorion.eu/v1

/usage-events

Returns paginated raw usage events for the org, newest first - the read side of POST /usage-events. All filter params AND together; multi-value metric_key is repeatable or comma-separated.

List usage events › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

customer_id

string

Filter by customer UUID

product_id

string

Filter by product UUID

subscription_id

string

Filter by subscription UUID

metric_key

string

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List usage events › Responses

array | null · required

object · required

Ingest a usage event (fire-and-forget billing)

POST

https://api.kontorion.eu/v1

/usage-events

Ingest a usage event (fire-and-forget billing) › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Ingest a usage event (fire-and-forget billing) › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

customer_id

string · uuid

Customer that consumed the metric.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Named dimension values used to select the price tier.

external_cost_amount

string · pattern: ^-?\d+(\.\d+)?$

Caller-supplied wholesale cost (COGS) fed to cost-plus formulas, MAJOR units; requires external_cost_currency.

Example: 49.5

external_cost_currency

string

ISO 4217 currency of external_cost_amount; one currency per (subscription, metric) group.

hold_id

string · uuid

Reserve hold this event captures against; null for direct (non-reserve) ingest.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

idempotency_key

string

Caller key that dedupes replays of the same event; required.

object

Arbitrary caller-supplied key/value annotations carried on the event.

metric_key

string · maxLength: 100

Metric this event records usage for; must match the product's meter binding.

Example: api_calls

price_key

string · maxLength: 100

Price key selecting a tier for keyed products; required when the product exposes keyed prices.

object

Named numeric variables bound into the price formula at finalize time.

product_id

string · uuid

Metered product the event is billed under.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

quantity

string · pattern: ^-?\d+(\.\d+)?$

Number of metric units to record; must be non-negative.

Example: 49.5

subscription_id

string · uuid

Subscription the usage is charged against.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

timestamp

string · date-time

When the usage occurred; omitted or zero stamps the server's ingest time. Set explicitly for backfill/historical imports.

wallet_currency

string

ISO 4217 currency pinning the event to a specific wallet; the wallet must exist for (customer_id, wallet_currency). Null uses the customer's preferred-currency cascade.

Ingest a usage event (fire-and-forget billing) › Responses

Created

required

Time-bucketed usage aggregate

GET

https://api.kontorion.eu/v1

/usage-events/aggregate

Server-side aggregation over the usage_events hypertable. Caps the window at MaxAggregateBuckets at the requested resolution.

Time-bucketed usage aggregate › query Parameters

since

string · required

Window lower bound (RFC3339)

bucket

string

Bucket size: hour | day (default) | week

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

Filter by metric_key. Repeatable or comma-separated

top

string

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

Time-bucketed usage aggregate › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Time-bucketed usage aggregate › Responses

object · required