Usage

4 calls. Every request needs the Authorization header: see the overview.

usage.breakdown

GET /usage/breakdown

Totals grouped by one dimension.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

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

Response: UsageBreakdown (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/usage/breakdown" \
  -H "Authorization: $MAITENTO_AUTH"

const byModel = await mt.usage.breakdown({ from: new Date("2026-10-01"), groupBy: "model" });

mt.usage.breakdown(group_by="model", limit=10)

usage.runs

GET /usage/runs

Individual runs with their usage (truncated says more matched than were returned).

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

Name	Type	Required	Description
from	string		The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: to minus 7 days.
to	string		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[]		Namespace names, matched as GET /processes matches them. The name a deleted or renamed namespace had also matches.
type	string[]		Kinds of run: Interaction, App, Capsule or CodePipeline (case-insensitive).
definitionId	string[]		Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include.
version	string[]		Definition versions, as {definitionId}:{version}.
agent	string[]		Agent names: the interaction or code pipeline agents whose turns or steps used the tokens.
provider	string[]		The AI providers that served interaction turns, such as Anthropic.
model	string[]		Model names.
engine	string[]		Code pipeline engines, as CodeEngineType names.
credentialKind	string[]		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[]		Pricing tiers, for models whose price depends on how many tokens a request uses.
outcome	string[]		How the runs ended: InProgress, Finished, Error or Killed.
startedBy	string[]		What started the runs: User, Automation or Parent.
triggerId	string[]		Ids of the users or automations that started the runs.
rootDefinitionId	string[]		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.
sort	string		What to order runs by, descending: tokens (default), runtime, execution or date.
limit	integer		How many runs: 1 to 200 (clamped), default 50.

Response: UsageRunPage (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/usage/runs" \
  -H "Authorization: $MAITENTO_AUTH"

const runs = await mt.usage.runs({ namespace: "support", sort: "cost", limit: 50 });

mt.usage.runs(outcome="Error", limit=50)

usage.series

GET /usage/series

A time series of one metric, bucketed and optionally grouped.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

Name	Type	Required	Description
from	string		The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: to minus 7 days.
to	string		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[]		Namespace names, matched as GET /processes matches them. The name a deleted or renamed namespace had also matches.
type	string[]		Kinds of run: Interaction, App, Capsule or CodePipeline (case-insensitive).
definitionId	string[]		Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include.
version	string[]		Definition versions, as {definitionId}:{version}.
agent	string[]		Agent names: the interaction or code pipeline agents whose turns or steps used the tokens.
provider	string[]		The AI providers that served interaction turns, such as Anthropic.
model	string[]		Model names.
engine	string[]		Code pipeline engines, as CodeEngineType names.
credentialKind	string[]		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[]		Pricing tiers, for models whose price depends on how many tokens a request uses.
outcome	string[]		How the runs ended: InProgress, Finished, Error or Killed.
startedBy	string[]		What started the runs: User, Automation or Parent.
triggerId	string[]		Ids of the users or automations that started the runs.
rootDefinitionId	string[]		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.
metric	string		The measure: tokens (default), input, output, cacheRead, cacheWrite, reasoning, runtime, execution, runs, steps, stepRuntime, toolCalls, webSearches, webPages, webDownloads, imageDescriptions, webCredits or webBytes.
bucket	string		The bucket size: hour, day or week. Omitted: chosen from the range’s length.
groupBy	string		A dimension to split the series by (any groupBy a breakdown takes), or tokenType with metric=tokens. Omitted: one total series.
top	integer		How many of the largest groups get a series of their own: 1 to 10 (clamped), default 5. The rest form one “other” series.

Response: UsageSeries (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/usage/series" \
  -H "Authorization: $MAITENTO_AUTH"

const daily = await mt.usage.series({ from: new Date("2026-10-01"), metric: "cost", bucket: "day" });

mt.usage.series(metric="cost", bucket="day", namespace="demo")

usage.summary

GET /usage/summary

Totals for the window.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

Name	Type	Required	Description
from	string		The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: to minus 7 days.
to	string		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[]		Namespace names, matched as GET /processes matches them. The name a deleted or renamed namespace had also matches.
type	string[]		Kinds of run: Interaction, App, Capsule or CodePipeline (case-insensitive).
definitionId	string[]		Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include.
version	string[]		Definition versions, as {definitionId}:{version}.
agent	string[]		Agent names: the interaction or code pipeline agents whose turns or steps used the tokens.
provider	string[]		The AI providers that served interaction turns, such as Anthropic.
model	string[]		Model names.
engine	string[]		Code pipeline engines, as CodeEngineType names.
credentialKind	string[]		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[]		Pricing tiers, for models whose price depends on how many tokens a request uses.
outcome	string[]		How the runs ended: InProgress, Finished, Error or Killed.
startedBy	string[]		What started the runs: User, Automation or Parent.
triggerId	string[]		Ids of the users or automations that started the runs.
rootDefinitionId	string[]		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.

Response: UsageSummary (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/usage/summary" \
  -H "Authorization: $MAITENTO_AUTH"

const totals = await mt.usage.summary({ from: new Date("2026-10-01"), to: new Date("2026-11-01") });

mt.usage.summary(from_="2026-10-01T00:00:00Z", to="2026-10-26T00:00:00Z")