Usage
client.usage reads append-only per-Turn usage after it has been rolled up daily. Results report token counts, request counts, and duration in milliseconds; they are operational measurements, not billing records.
Overview
Queries accept from, to, agentId, sessionId, userId, groupBy, and limit. Supply both date bounds or neither; the default is the last 30 days ending today in UTC, and a custom range spans at most 31 days. groupBy defaults to day; limit applies to top Sessions and defaults to 50.
Methods
get()
get(query?: Partial<UsageQuery>): Promise<UsageResponse> — GET /v1/usage. Filter by Agent, Session, or Attribution. sessionId: "" selects stateless completion/object Turns and userId: "" selects tenant-level usage.
getForAgent()
getForAgent(agentId: string, query?: Partial<UsageQuery>): Promise<UsageResponse> — GET /v1/agents/:agentId/usage. The path fixes the Agent scope; a query agentId, if supplied, does not override it.
Types
| Type | Fields |
|---|---|
UsageQuery | Inclusive from/to; optional Agent, Session, and userId filters; groupBy selects day, Agent, model, Session, or user; limit |
UsageBucket | Nullable grouping keys plus inputTokens, outputTokens, requestCount, and durationMs |
UsageResponse | buckets and totals in the same four units |
Fields unrelated to the selected grouping are null. For user grouping, userId: "" remains the tenant-level bucket; stateless bucket Session IDs are null. See objects and schemas and pagination and filtering.
Errors
Partial, reversed, or oversized date ranges and invalid grouping/limits are invalid_request. See errors.
Example
import { BlazingAgents } from "@blazing-agents/sdk";
const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });
const agentId = "ag_0123456789abcdef";
const tenantUsage = await client.usage.get({
from: "2026-07-01",
to: "2026-07-20",
groupBy: "day",
});
const usage = await client.usage.getForAgent(agentId, {
from: "2026-07-01",
to: "2026-07-20",
userId: "user-42",
groupBy: "session",
limit: 20,
});
console.log(tenantUsage.totals.requestCount, usage.totals.durationMs);