Usage analytics

Usage analytics measures traffic and compute consumption over a time range. Use client.usage.metrics(...) to query one app, an owner or workspace, or every resource available to the current viewer.

Features

Flexible scopes

Pass app for one app, owner for a user or workspace, or omit both to query usage for the current viewer. app and owner cannot be used together.

Request metrics

Inspect total and cached requests, HTTP status groups, unique users, request duration, and cached or served bytes.

Workload metrics

Measure workloads, memory, CPU time, and network ingress or egress for the selected scope and time range.

Time-grouped results

Read aggregate values from totals and trend data from grouped. Group results into 5-minute, 15-minute, hourly, daily, or weekly buckets.

Common workflow

Choose an app, owner, or current-viewer scope.
Set the start and end of the usage window with dates or ISO date strings.
Choose a grouping interval such as BY_HOUR or BY_DAY.
Read aggregate usage from totals and iterate over grouped for trends.

SDK examples

Query app and workspace usage

Fetch daily metrics for one app and aggregate metrics for a workspace, then inspect request and compute totals.

analytics.js

const appUsage = await client.usage.metrics({
  app: "da_XYZ",
  start: new Date("2026-06-01T00:00:00Z"),
  end: new Date("2026-06-30T00:00:00Z"),
  groupedBy: "BY_DAY",
});
 
console.log(appUsage.totals.requests.totalRequests);
console.log(appUsage.totals.requests.http5xx);
console.log(appUsage.totals.workloads.realCpuTimeMillis);
 
for (const day of appUsage.grouped) {
  console.log(day.groupedAt, day.requests.totalRequests);
}
 
const workspaceUsage = await client.usage.metrics({
  owner: "my-workspace",
  start: "2026-06-01T00:00:00Z",
  end: "2026-06-30T00:00:00Z",
});
 
console.log(workspaceUsage.scope);
console.log(workspaceUsage.totals.workloads.networkEgressBytes);

Source: stackmachine/sdks JavaScript examples.