List LLM usage
Returns time-bucketed LLM call counts and input/output tokens by model over the [since, until) window. rollup selects hour or day buckets. Scoped to your organization.
Requires: usage:read
Authorizations
A Modus personal access token (modus_<orgUuid>_<prefix>_<secret>) or an OAuth 2.1 access token, sent as Authorization: Bearer <token>.
Query Parameters
ISO8601 start of the query window (inclusive).
"2026-05-01T00:00:00.000Z"
ISO8601 end of the query window (exclusive).
"2026-05-08T00:00:00.000Z"
Time bucket size for the response rows.
hour, day "hour"
Filter by one or more model names (repeat the query param).
Dimension to group usage rows by.
all, skill, agent, interface, model, attribution "skill"
Filter by one or more scope IDs (repeat the query param).
Filter by one or more workflow IDs (repeat the query param).
Filter by one or more user IDs (repeat the query param).
Filter by one or more interface names (repeat the query param).
Filter by one or more acting-user emails (repeat the query param). Matched together with user_id: a row matches if its user_email OR its user_id is in the given sets.
Response
Organization id (org_xxx) the result is scoped to.
hour, day Dimension that was grouped by in this response.
all, skill, agent, interface, model, attribution