UsageBreakdownRequest

What to group a usage breakdown by, how to order it, and the usual usage filters.

Kind: an object, used in requests.

Fields

Field	Type	Required	Description
groupBy	string | null		Required: the dimension to group by: namespace, type, definition, version, agent, provider, model, engine, credentialKind, tier, outcome, startedBy, trigger or root.
sort	string | null		The measure to order rows by, descending: any metric a series takes (default tokens).
limit	integer | null		How many rows: 1 to 500 (clamped), default 50. The rest are summed into other.
from	string | null		The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: to minus 7 days.
to	string | null		The end of the range: ISO 8601 with an offset, rounded up to the hour (UTC). Default: the start of the next hour.
namespace	string[] | null		Namespace names, matched as GET /processes matches them. The name a deleted or renamed namespace had also matches.
type	string[] | null		Kinds of run: Interaction, App, Capsule or CodePipeline (case-insensitive).
definitionId	string[] | null		Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include.
version	string[] | null		Definition versions, as {definitionId}:{version}.
agent	string[] | null		Agent names: the interaction or code pipeline agents whose turns or steps used the tokens.
provider	string[] | null		The AI providers that served interaction turns, such as Anthropic.
model	string[] | null		Model names.
engine	string[] | null		Code pipeline engines, as CodeEngineType names.
credentialKind	string[] | null		Whose provider key served the tokens: Own (the tenant’s or the run’s own key), Platform (Maitento’s) or Unknown (none was recorded).
tier	string[] | null		Pricing tiers, for models whose price depends on how many tokens a request uses.
outcome	string[] | null		How the runs ended: InProgress, Finished, Error or Killed.
startedBy	string[] | null		What started the runs: User, Automation or Parent.
triggerId	string[] | null		Ids of the users or automations that started the runs.
rootDefinitionId	string[] | null		Definition ids of the runs at the top of the tree: everything an app (or any top-level run) caused, the runs it started included.

Example

{
  "groupBy": "...",
  "sort": "...",
  "limit": 0,
  "from": "...",
  "to": "...",
  "namespace": [
    "..."
  ],
  "type": [
    "..."
  ],
  "definitionId": [
    "..."
  ],
  "version": [
    "..."
  ],
  "agent": [
    "..."
  ],
  "provider": [
    "..."
  ],
  "model": [
    "..."
  ],
  "engine": [
    "..."
  ],
  "credentialKind": [
    "..."
  ],
  "tier": [
    "..."
  ],
  "outcome": [
    "..."
  ],
  "startedBy": [
    "..."
  ],
  "triggerId": [
    "..."
  ],
  "rootDefinitionId": [
    "..."
  ]
}