UsageQueryRequest

The time range and filters every /usage call takes. Every filter is optional; filters combine with AND across parameters and OR within one. A parameter may be repeated, and each value may also be comma-separated, except agent, provider, model, engine and tier, whose values are taken whole. At most 50 values per parameter. The value ~none matches “no value” for that dimension.

Kind: an object, used in requests.

Fields

Field	Type	Required	Description
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

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