Report on usage - Namespace Documentation

client.usage reports what a workspace consumed. Compute, volume, and object storage usage are reported per billing period, while time series, concurrency, and instance reports answer more detailed questions. The examples on this page use a Compute client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

Period-based methods take periodStart and periodEnd as calendar dates, not JavaScript Date objects. Each one is a GetUsageRequest_Date message, which you pass as an object literal. Both bounds are inclusive and must fall in the same month. When periodStart is omitted, the period starts on the first day of the current month.

`usage.getUsage()`

Return compute usage for a billing period, in total and broken down per day.

Example

const usage = await client.usage.getUsage({
  periodStart: { year: 2026, month: 9, day: 1 },
});

console.log(usage.total?.instanceMinutes?.unit);

for (const day of usage.perDay) {
  console.log(day.day, day.total?.instanceMinutes?.wall);
}

API reference

getUsage(
  request: MessageInitShape<typeof GetUsageRequestSchema>,
  options?: CallOptions,
): Promise<GetUsageResponse>

Arguments and options

{ year: number; month: number; day: number }

The first day of the period. Defaults to the first day of the current month.

{ year: number; month: number; day: number }

The last day of the period, inclusive. Must be in the same month as periodStart.

StringMatcher

Only include usage from instances on a matching platform, such as linux/amd64.

StringMatcher

Only include usage from instances with a matching shape, such as 2x8.

StringMatcher

Only include usage from instances with a matching GitHub profile.

StringMatcher

Only include usage from instances with a matching GitHub repository.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetUsageResponse with total for the period and perDay records. Both report instanceMinutes and builds:

Minutes

unit counts compute units, where one unit is 1 vCPU and 2 GB of RAM for a minute. wall counts the total elapsed minutes instances were running.

Builds

count is the number of build requests processed, with unitMinutes and wallMinutes reported the same way as for instances.

`usage.getVolumeUsage()`

Return volume usage for a billing period. This covers cache volume snapshots and at-rest storage, and persistent block volume storage.

Example

const { total } = await client.usage.getVolumeUsage({
  periodStart: { year: 2026, month: 9, day: 1 },
});

const cacheSnapshotGbHours = Number(total!.cacheSnapshotGbMinutes) / 60;
console.log(cacheSnapshotGbHours);

API reference

getVolumeUsage(
  request: MessageInitShape<typeof GetVolumeUsageRequestSchema>,
  options?: CallOptions,
): Promise<GetVolumeUsageResponse>

Arguments and options

{ year: number; month: number; day: number }

The first day of the period. Defaults to the first day of the current month.

{ year: number; month: number; day: number }

The last day of the period, inclusive.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetVolumeUsageResponse whose total reports three bigint values:

bigint

Active cache volume snapshot usage, in GB-minutes. Divide by 60 for GB-hours.

bigint

At-rest cache volume storage, in MB-minutes. Divide by 1024 * 60 * 24 for GB-days.

bigint

At-rest persistent volume storage, in GB-minutes. Divide by 60 * 24 for GB-days.

`usage.getArtifactUsage()`

Return object storage usage per product, covering at-rest storage and reads.

Example

const { products } = await client.usage.getArtifactUsage({
  periodStart: { year: 2026, month: 9, day: 1 },
});

for (const product of products) {
  console.log(product.product, product.storageGbMinutes, product.readsBytes);
}

API reference

getArtifactUsage(
  request: MessageInitShape<typeof GetArtifactUsageRequestSchema>,
  options?: CallOptions,
): Promise<GetArtifactUsageResponse>

Arguments and options

{ year: number; month: number; day: number }

The first day of the period. Defaults to the first day of the current month.

{ year: number; month: number; day: number }

The last day of the period, inclusive.

ArtifactProduct[]

Restricts the results to the given products: REGISTRY, TURBOREPO, GITHUB_ARTIFACTS, BAZEL, or GRADLE. When empty, all products are reported.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetArtifactUsageResponse with one entry per product, each reporting storageGbMinutes and readsBytes.

`usage.getUsageTimeSeries()`

Return compute usage as a time series over an explicit time range, with optional filters and breakdowns.

Example

import { timestampFromDate } from "@bufbuild/protobuf/wkt";

const { timeSeries } = await client.usage.getUsageTimeSeries({
  startTime: timestampFromDate(new Date("2026-09-01T00:00:00Z")),
  endTime: timestampFromDate(new Date("2026-09-08T00:00:00Z")),
  breakdownBy: ["shape"],
});

console.log(timeSeries?.timestamps.length);

API reference

getUsageTimeSeries(
  request: MessageInitShape<typeof GetUsageTimeSeriesRequestSchema>,
  options?: CallOptions,
): Promise<GetUsageTimeSeriesResponse>

Arguments and options

Timestamp

required

Start of the time range, inclusive.

Timestamp

required

End of the time range, exclusive.

UsageFilter

Restricts the data by platform, shape, purpose, GitHub repository, branch, workflow, job, profile, and conclusion, or by Buildkite organization, pipeline, repository, branch, job, and state. Each field is a StringMatcher.

string[]

Dimension names to break the results down by. The response contains a separate time series per unique combination of breakdown values.Valid values are platform, shape, purpose, github_repository, github_branch, github_workflow_name, github_job_name, buildkite_org_id, buildkite_pipeline_id, buildkite_pipeline_slug, buildkite_repository, buildkite_branch, buildkite_job_name, and buildkite_job_state. The filter accepts some dimensions that are not valid here, such as github_profile.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetUsageTimeSeriesResponse with a timeSeries. The series holds a shared timestamps array and named doubles, integers, and strings series aligned to it.

`usage.getConcurrency()`

Return the configured concurrency limits and current active concurrency, per platform.

Example

const { concurrency } = await client.usage.getConcurrency({});

for (const platform of concurrency) {
  console.log(platform.name, platform.platforms, platform.activeConcurrency);
}

API reference

getConcurrency(
  request: MessageInitShape<typeof GetConcurrencyRequestSchema>,
  options?: CallOptions,
): Promise<GetConcurrencyResponse>

Arguments and options

The request has no fields. Pass an empty object.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetConcurrencyResponse with one PlatformConcurrency per platform group. Each entry carries a display name such as Linux, the platforms it covers such as linux/amd64, the configured limits, and the activeConcurrency in use. See billing and limits for how limits are set.

`usage.generateReport()`

Stream a detailed report listing every compute instance created in a time range. The server emits entries in batches.

Example

import { timestampFromDate } from "@bufbuild/protobuf/wkt";

for await (const batch of client.usage.generateReport({
  startTime: timestampFromDate(new Date("2026-09-01T00:00:00Z")),
  endTime: timestampFromDate(new Date("2026-09-08T00:00:00Z")),
})) {
  for (const entry of batch.entries) {
    console.log(entry.instanceId, entry.resourcesCpu, entry.destroyedAt);
  }
}

API reference

generateReport(
  request: MessageInitShape<typeof GenerateReportRequestSchema>,
  options?: CallOptions,
): AsyncIterable<GenerateReportResponse>

Arguments and options

Timestamp

required

Start of the time range, inclusive. Only instances created within the range are reported.

Timestamp

required

End of the time range, exclusive.

UsageFilter

The same filter accepted by getUsageTimeSeries().

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an async iterable of GenerateReportResponse. Each message carries a batch of entries, and the server chooses how many entries to place in each message. An InstanceReportEntry reports the instance ID, creation, start, and destruction timestamps, requested and observed CPU and memory, attached volumes, and the GitHub or Buildkite job the instance served.

Report execution is constrained to 30 seconds. Any number of records can be downloaded within that window. Narrow the time range or the filter if a report does not complete.

Billing and limits

How usage is priced and where workspace limits apply.

Usage explorer

Explore the same usage data in the dashboard.

​usage.getUsage()

​Example

​API reference

​Arguments and options

​Return value

​usage.getVolumeUsage()

​Example

​API reference

​Arguments and options

​Return value

​usage.getArtifactUsage()

​Example

​API reference

​Arguments and options

​Return value

​usage.getUsageTimeSeries()

​Example

​API reference

​Arguments and options

​Return value

​usage.getConcurrency()

​Example

​API reference

​Arguments and options

​Return value

​usage.generateReport()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Billing and limits

Usage explorer

`usage.getUsage()`

Example

API reference

Arguments and options

Return value

`usage.getVolumeUsage()`

Example

API reference

Arguments and options

Return value

`usage.getArtifactUsage()`

Example

API reference

Arguments and options

Return value

`usage.getUsageTimeSeries()`

Example

API reference

Arguments and options

Return value

`usage.getConcurrency()`

Example

API reference

Arguments and options

Return value

`usage.generateReport()`

Example

API reference

Arguments and options

Return value

Related documentation