UsageSeriesRequest

Which measure to chart, in what buckets, split how, and the usual usage filters.

Kind: an object, used in requests.

Fields

Field	Type	Required	Description
metric	string | null		The measure: tokens (default), input, output, cacheRead, cacheWrite, reasoning, runtime, execution, runs, steps, stepRuntime, toolCalls, webSearches, webPages, webDownloads, imageDescriptions, webCredits or webBytes.
bucket	string | null		The bucket size: hour, day or week. Omitted: chosen from the range’s length.
groupBy	string | null		A dimension to split the series by (any groupBy a breakdown takes), or tokenType with metric=tokens. Omitted: one total series.
top	integer | null		How many of the largest groups get a series of their own: 1 to 10 (clamped), default 5. The rest form one “other” series.
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

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