Skip to main content
GET
Per-bucket credits spent for the calling user within an instance scope

Authorizations

x-access-token
string
header
required

JWT token passed in x-access-token header

Query Parameters

instanceId
string
required

Either the literal string personal (personal-scope usage) or the ObjectId of an institution the caller is a member of.

window
enum<integer>
default:30

Number of days of history to aggregate. Invalid values fall back to 30.

Available options:
7,
14,
30,
90,
180
interval
enum<string>

Bucket granularity. Invalid or omitted values fall back to a window-appropriate default (daily ≤30d, weekly otherwise).

Available options:
daily,
weekly,
monthly
scope
enum<string>
default:own

own (default) returns the calling user's own usage for the instance. all returns aggregated usage for ALL users of the institution — but is honored ONLY when the caller is an admin of that institution (an admin with institutions.edit). For non-admins, or for personal scope, it silently falls back to own (never leaks other users' data). The EFFECTIVE scope is echoed in the response scope field. The 60s TTL cache key includes the effective scope, so own and all-users payloads never collide.

Available options:
own,
all
models
enum<string>

1 asks for the models split (the window's messages by the model they ran on). Honored only for an administrator of the Digital Twin; ignored otherwise.

Available options:
1

Response

Bucketed usage payload

success
boolean
Example:

true

instanceId
string
Example:

"personal"

window
integer
Example:

30

interval
string
Example:

"daily"

scope
enum<string>

The EFFECTIVE scope applied (falls back to own if the caller isn't an institution admin).

Available options:
own,
all
Example:

"own"

currency
string
Example:

"usd"

buckets
object[]

One entry per granular bucket, ascending by start.

totals
object
models
object[]

When models=1 is asked by one of the Digital Twin's administrators: the window's messages split by the model they ran on, most messages first, in the same scope as the buckets. Models are named for people (custom AI models by their own name); "File uploads and other activity" groups uploaded files (and the models that summarize or analyze them), sign-ins and other entries that are not chat messages, "Other models" the models the platform does not know. Credits are rounded up per model, so they may not add up to the total exactly. Absent for anyone else.