Monitor usage and quotas

Use usage reports to measure settled Turns and quotas to apply tenant-wide monthly safety ceilings. This guide queries tenant and Agent totals, updates one policy value, and reads it back.

Outcome

You will verify tenant and Agent usage totals for a bounded window and confirm that a monthly request ceiling was persisted.

You need a backend SDK client, a known agentId, an inclusive UTC date window (from and to), and quota values chosen from your own operational policy. Review Usage and quotas and end-user Attribution.

Query tenant usage

Call usage.get with both date bounds and one supported groupBy value: day, agent, model, session, or user. The response contains grouped buckets and ungrouped totals for input tokens, output tokens, requests, and duration in milliseconds.

Query one Agent

getForAgent applies the Agent ID from its path and accepts the same date, Session, userId, grouping, and limit query fields. Both usage methods support userId; "" selects tenant-level Attribution and a nonempty value selects one tenant-chosen End-user identifier.

Set quota headroom

Read the current settings before patching. A quota update is a complete object with monthlyTokenLimit, monthlyRequestLimit, and resetDay. Either ceiling may be null; quota: null removes the quota row. Choose ceilings below the capacity or budget that should trigger intervention—no platform numeric default is implied.

Verify totals and settings

const tenantUsage = await client.usage.get({ from, to, groupBy: "agent" });
const agentUsage = await client.usage.getForAgent(agentId, {
  from,
  to,
  groupBy: "day",
});

if (tenantUsage.totals.requestCount < agentUsage.totals.requestCount) {
  throw new Error("Agent requests exceed the tenant total");
}

const current = await client.tenant.get();
const updated = await client.tenant.patch({
  quota: {
    monthlyRequestLimit,
    monthlyTokenLimit: current.quota?.monthlyTokenLimit ?? null,
    resetDay,
  },
});
const verified = await client.tenant.get();

if (updated.quota?.monthlyRequestLimit !== monthlyRequestLimit) {
  throw new Error("The quota update was not returned");
}
if (verified.quota?.monthlyRequestLimit !== monthlyRequestLimit) {
  throw new Error("The quota update was not persisted");
}
console.log(tenantUsage.totals, agentUsage.totals);

In this example, monthlyRequestLimit and resetDay come from your deployment policy. Valid reset days are 1 through 28.

Respond to quota states

Usage is written once per Turn after settlement, including Turns that error or abort. A Task canceled while running has started a Turn and is metered; a queued cancellation or quota preflight block that never starts a Turn is not.
Quota checks sum requests and input plus output tokens from the most recent configured reset day. The gate rejects only when settled usage is already over a ceiling, so a Turn at the ceiling can start and an in-flight Turn can overshoot it.
No quota row means unlimited. A null ceiling leaves only that dimension unlimited.
Synchronous quota denial is a quota_exceeded error. A Task denied by its preflight or normal Turn gate ends as terminal blocked; execution errors end as failed.

Production notes

Custom usage windows require both from and to, and both date bounds are inclusive. The endpoints may be at most 31 days apart, so the largest accepted window can contain 32 UTC calendar dates. Omitting both uses the default window ending today in UTC. Only groupBy: "session" applies the limit as a top-N selection; totals still cover the full filtered window.

The daily rollup is updated in the same database transaction as the per-Turn usage row. Reads therefore include settled Turns, but not a currently running Turn that has not recorded usage. Leave headroom and alert before the ceiling rather than treating quota as a billing-grade hard stop. See Limits and reliability and Tasks and schedules.

SDK and REST reference

See usage.get, usage.getForAgent, tenant.get, and tenant.patch. The matching REST operations are get usage, get Agent usage, get tenant settings, and update tenant settings.