---
title: "Usage"
description: "Query request and workload usage metrics with the JavaScript SDK."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

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

1. Choose an app, owner, or current-viewer scope.
2. Set the start and end of the usage window with dates or ISO date strings.
3. Choose a grouping interval such as `BY_HOUR` or `BY_DAY`.
4. 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.

```javascript
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);
```

```python
app_usage = client.usage.metrics(
    app="da_XYZ",
    start="2026-06-01T00:00:00Z",
    end="2026-06-30T00:00:00Z",
    grouped_by="BY_DAY",
)
print(app_usage.totals.requests.total_requests)
print(app_usage.totals.requests.http5xx)
print(app_usage.totals.workloads.real_cpu_time_millis)

for day in app_usage.grouped:
    print(day.grouped_at, day.requests.total_requests)

workspace_usage = client.usage.metrics(
    owner="my-workspace",
    start="2026-06-01T00:00:00Z",
    end="2026-06-30T00:00:00Z",
)
print(workspace_usage.scope)
print(workspace_usage.totals.workloads.network_egress_bytes)
```

## Related docs

- [Get app by ID](/apps/get-by-id)
- [Serverless Compute](/apps)

> Source: [stackmachine/sdks](https://github.com/stackmachine/sdks/tree/main/js) JavaScript examples.

Source: https://docs.stackmachine.com/usage/index.mdx