Skip to main content
GET
List LLM usage

Authorizations

Authorization
string
header
required

A Modus personal access token (modus_<orgUuid>_<prefix>_<secret>) or an OAuth 2.1 access token, sent as Authorization: Bearer <token>.

Query Parameters

since
string
required

ISO8601 start of the query window (inclusive).

Example:

"2026-05-01T00:00:00.000Z"

until
string
required

ISO8601 end of the query window (exclusive).

Example:

"2026-05-08T00:00:00.000Z"

rollup
enum<string>
required

Time bucket size for the response rows.

Available options:
hour,
day
Example:

"hour"

model
string[]

Filter by one or more model names (repeat the query param).

Example:
group_by
enum<string>
default:skill

Dimension to group usage rows by.

Available options:
all,
skill,
agent,
interface,
model,
attribution
Example:

"skill"

skill_id
string[]

Filter by one or more scope IDs (repeat the query param).

Example:
agent_id
string[]

Filter by one or more workflow IDs (repeat the query param).

Example:
user_id
string[]

Filter by one or more user IDs (repeat the query param).

Example:
interface
string[]

Filter by one or more interface names (repeat the query param).

Example:
user_email
string[]

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.

Example:

Response

org_id
string
required

Organization id (org_xxx) the result is scoped to.

since
string
required
until
string
required
rollup
enum<string>
required
Available options:
hour,
day
group_by
enum<string>
required

Dimension that was grouped by in this response.

Available options:
all,
skill,
agent,
interface,
model,
attribution
buckets
object[]
required
totals
object
required