#Usage per Tenant

How much did each organization, tenant or service do? Use the usage API (or the Usage page of a tenant in the Enterprise UI) when you account for the organizations and tenants you run for your own customers.

Usage is recorded by the same call that counts an operation for your walt.id license, writes its event and its eIDAS audit entry. Usage, license usage and the enterprise_usage_total metric therefore always count the same operations the same way.

#What is counted

Type	One unit is	Counted when
`CREDENTIAL_ISSUED`	a credential delivered by an issuer	the credential endpoint returned it
`VERIFICATION_SESSION`	a verification session that reached a result	the wallet's response was processed, successful or failed
`WALLET_CREATED`	a wallet service created	it was stored
`CREDENTIAL_RECEIVED`	a credential stored in a wallet	it was stored (exact on partial failures)
`CREDENTIAL_PRESENTED`	a credential presented from a wallet	the presentation was sent
`KEY_OPERATION`	a key generated, stored or imported in a KMS	the key was created (not for one that already existed)
`DID_RESOLUTION`	a DID resolved through the DID service	it resolved
`API_KEY_USAGE`	a request authenticated with an API key	the request was authenticated

Failed operations are not counted, except verifications, where a failed verification is a result too.

#Query usage

CURL

Endpoint: /v1/usage | API Reference

Requires the view-usage permission on target. A role scoped to one tenant can read that tenant's usage, but not the organization's.

Example Request

curl -X 'GET' \
  'https://{orgID}.enterprise.sandbox.walt.id/v1/usage?target=waltid.customer-a&from=2026-09-01&to=2026-10-01&granularity=month&groupBy=tenant,type' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Query Parameters

target: String (optional) - A tenant (includes its sub-tenants), a service, or the organization. Defaults to the organization.
from, to: String (optional) - Dates (2026-09-01) or instants (2026-09-01T00:00:00Z), UTC, to exclusive, at most 400 days apart. Defaults to the last 30 days. Usage is counted per hour, so the range is widened to whole hours; the response gives the range used.
granularity: String (optional) - hour, day (default), month or total.
groupBy: String (optional) - Any of tenant, service, type, comma-separated. Defaults to type.

Response

200 - Usage of the target, per period and the requested groups.

Example Response

{
  "organization": "waltid",
  "target": "waltid.customer-a",
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "granularity": "month",
  "groupBy": ["tenant", "type"],
  "rows": [
    { "period": "2026-09-01T00:00:00Z", "tenant": "waltid.customer-a", "type": "CREDENTIAL_ISSUED", "count": 1250 },
    { "period": "2026-09-01T00:00:00Z", "tenant": "waltid.customer-a", "type": "VERIFICATION_SESSION", "count": 980 }
  ]
}

A row's tenant is null for services directly under the organization, and its service is null for usage no service was addressed for (API key requests are counted for the organization).

Counts are written every minute, so the last minute is not included yet. A pod that stops abruptly loses at most its last minute of counts. Hourly counts are kept for 400 days, then removed by MongoDB; export them (for example monthly totals) if you need them longer.

#Query the database directly

Usage is stored in the usage_aggregates collection. Each document is one tenant, service, type and hour as counted by one pod (pod), so always sum count over the documents you select:

{ "organization": "waltid", "tenant": "waltid.customer-a", "service": "waltid.customer-a.issuer",
  "type": "CREDENTIAL_ISSUED", "hour": ISODate("2026-09-14T10:00:00Z"), "pod": "3f6c...", "count": 42 }

Issuances per tenant in September:

db.usage_aggregates.aggregate([
  { $match: { organization: "waltid", type: "CREDENTIAL_ISSUED",
              hour: { $gte: ISODate("2026-09-01"), $lt: ISODate("2026-10-01") } } },
  { $group: { _id: "$tenant", count: { $sum: "$count" } } },
  { $sort: { _id: 1 } }
])

To include sub-tenants, match the tenant path as a prefix instead: tenant: { $regex: "^waltid\\.customer-a(\\.|$)" }.

#License usage

GET /license/usage (super administrators) shows what counts against the walt.id license, for the whole installation and the current license period. It does not split by organization or tenant; the usage API does.

Last updated on November 3, 2026

How to retrieve Metrics Events & Metrics