Usage and quotas

Usage records what each Turn consumed and rolls those records up for reporting. A quota is an optional, Tenant-set monthly token or request safety ceiling; it is not a billing entitlement, plan limit, credit balance, or invoice meter.

What is metered

Every Turn appends one usage record with input tokens, output tokens, one request count, duration, Agent Version, provider, model, Session or stateless marker, and Attribution. Daily rollups aggregate token, request, and duration fields for queries and quota windows.

Settlement runs for successful, failed, and cancelled Turns. A failure before the model reports usage can therefore record zero tokens but still records the request and duration. If an error or abort happens after completed model steps, tokens already reported by those steps remain in usage. Only a successful Turn changes an interactive Session transcript.

Query usage

Use client.usage.get() for the Tenant rollup or getForAgent() for one Agent. Queries return totals plus buckets grouped by day, agent, model, session, or user; filters include date range, Agent, Session, and userId. Supplying only one of the from and to date bounds is invalid, and a custom range is bounded by the service limits.

The first half of this example queries one grouped Tenant report:

import { BlazingAgents } from "@blazing-agents/sdk";

const apiKey = process.env.BLAZING_AGENTS_API_KEY;
if (!apiKey) throw new Error("BLAZING_AGENTS_API_KEY is required");

const client = new BlazingAgents({ apiKey });
const report = await client.usage.get({
  from: "2026-07-01",
  to: "2026-07-31",
  groupBy: "agent",
});

for (const bucket of report.buckets) {
  console.log(bucket.agentId, bucket.inputTokens + bucket.outputTokens);
}

const settings = await client.tenant.patch({
  quota: {
    monthlyTokenLimit: 1_000_000,
    monthlyRequestLimit: null,
    resetDay: 1,
  },
});

console.log(settings.quota?.monthlyTokenLimit, settings.quota?.resetDay);

Each non-empty grouped bucket has an agentId. The returned Tenant settings show a token ceiling of 1000000, an unlimited request dimension, and reset day 1.

Configure a quota

Update Tenant settings with positive monthly token and/or request ceilings and a reset day from 1 through 28. A null dimension is unlimited. Setting quota: null removes the quota row; omitting quota from an update leaves the current setting unchanged.

No quota row means unlimited, so enforcement fails open. The platform checks current-window usage before an ordinary Turn. A running Turn is not stopped when it crosses a ceiling, and concurrent Turns can overshoot before their usage settles.

Task runs have an additional preflight before creating their Session or waiting for Sandbox admission, followed by the ordinary Turn gate. A preflight denial ends the run as blocked without executing it.

Quota outcomes

Situation	Outcome
A synchronous Turn starts while current-window usage is over a configured ceiling	HTTP `429` with error code `quota_exceeded`
A Task run fails its preflight or later Turn quota gate	Terminal Task run status `blocked`; it is not `failed`
A Turn fails or is cancelled after consuming model work	Its request, duration, and any usage reported before the failure or abort remain recorded

A blocked Task run has no execution Session at the preflight path and frees the Task's active-run slot. A later scheduled fire may try again after usage or the quota window changes.

Production considerations

Monitor representative usage before enabling ceilings, then alert before the threshold rather than treating rejection as the first signal.
Calculate operational windows using the configured reset day and account for month boundaries.
Leave headroom for in-flight and concurrent Turns because quota enforcement is soft and can overshoot.
Keep failed and cancelled Turn usage visible in operational reporting.
Treat billing separately. The billing policy defines infrastructure charges and plan entitlements; this quota covers only the implemented Turn token and request counters.

See Tenancy and end-user attribution, Limits and reliability, and Tasks and schedules for related controls.