nsc instance report - Namespace Documentation

Generates a report of compute instances. instance report generates a CSV report of compute instances created in your workspace over a given time range. Each row describes a single instance, including its allocated and observed resource usage and, when applicable, the GitHub Actions or Buildkite job that triggered it. The report always contains the following columns:

instance_id
created_at, started_at, destroyed_at
resources_cpu, resources_ram_gb (allocated)
resources_cpu_actual_max, resources_ram_gb_actual_max_percent (observed)
cache_volume_hit (true if any attached volume had a cache hit, otherwise false)

If you’re using GitHub Actions and any instance in the report has GitHub Actions job data, the report also includes:

github_job_id, github_job_name, github_job_workflow_name
github_run_id, github_run_attempt
job_created_at, job_started_at, job_completed_at
profile, repository, branch, sender_login, conclusion

If you’re using Buildkite and any instance in the report has Buildkite job data, the report also includes:

buildkite_job_id, buildkite_job_name
buildkite_pipeline_slug, buildkite_pipeline_id
buildkite_build_id, buildkite_build_number
buildkite_job_created_at, buildkite_job_runnable_at
buildkite_job_started_at, buildkite_job_finished_at
buildkite_org_id, buildkite_repository, buildkite_branch, buildkite_job_state

A report containing both GitHub Actions and Buildkite job data includes both sets of columns. If neither is present, it contains only the instance columns.

Usage

nsc instance report --start <time> [flags]

--start is required. --end defaults to now if not provided. By default the report is written to a temporary file in /tmp; pass --out - to write to stdout, or --out <path> to write to a specific file.

Example

The following example generates a report starting at the specified time and writes it to stdout:

nsc instance report --start 2026-05-11T11:00:00Z --out -

The following example shows a GitHub Actions report:

Output

Writing output to path: stdout
instance_id,created_at,started_at,destroyed_at,resources_cpu,resources_ram_gb,resources_cpu_actual_max,resources_ram_gb_actual_max_percent,cache_volume_hit,github_job_id,github_job_name,github_job_workflow_name,github_run_id,github_run_attempt,job_created_at,job_started_at,job_completed_at,profile,repository,branch,sender_login,conclusion
iekjd1l47to3k,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:11:10 +0000 UTC,8,16,0.7,0.17460646,true,75349817393,go test,Go,25669248595,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:43 +0000 UTC,,namespacelabs/internal,main,github-merge-queue[bot],success
mcja6q4oi4kh2,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:12:07 +0000 UTC,16,32,0.6451724,0.14323927,true,75349827012,validate,Validate,25669251386,1,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:10:04 +0000 UTC,2026-05-11 12:11:29 +0000 UTC,,namespacelabs/internal,main,github-merge-queue[bot],success
a5gkg10as2tdg,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:10:46 +0000 UTC,2,4,0.94,0.2463041,true,75349817514,go lint,Go,25669248531,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:22 +0000 UTC,,namespacelabs/internal,main,github-merge-queue[bot],success

In the row above, instance iekjd1l47to3k was allocated 8 CPUs and 16 GiB of memory; during its lifetime it used at most 70% of the CPU and ~17% of the memory. It was created by the go test job of the Go workflow, GitHub run 25669248595. To investigate resource optimization opportunities on Namespace, it can be useful to use nsc instance report in combination with an LLM agent: Prompt

Agent Prompt

Based on GitHub job historical data over the last 7 days obtained via "nsc instance report", produce a short report of resource optimization opportunities for jobs (for the same job name, consistent low resource usage within a category)

Options

—start <time>

Start time of the report. Required.

—end <time>

End time of the report. Defaults to now if not provided.

—out <path>

Output file path. Creates a temporary file in /tmp if not provided. Use - for stdout.

—repository <repo>

GitHub repository (or repositories) to include in the report. Repeatable. Cannot be passed together with --exclude-repository.

—workflow <name>

GitHub workflow(s) to include in the report. Repeatable. Cannot be passed together with --exclude-workflow.

—jobname <name>

GitHub job name(s) to include in the report. Repeatable. Cannot be passed together with --exclude-jobname.

—branch <name>

GitHub branch(es) to include in the report. Repeatable. Cannot be passed together with --exclude-branch.

—platform <platform>

Platform(s) to include in the report (e.g. linux/amd64, linux/arm64). Repeatable. Cannot be passed together with --exclude-platform.

—shape <shape>

Instance shape(s) to include in the report. Repeatable. Cannot be passed together with --exclude-shape.

—purpose <purpose>

Instance purpose(s) to include in the report. Repeatable. Cannot be passed together with --exclude-purpose.

—profile <profile>

Runner profile(s) to include in the report. Repeatable. Cannot be passed together with --exclude-profile.

—buildkite-org-id <id>

Buildkite organization IDs to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-org-id.

—buildkite-pipeline-id <id>

Buildkite pipeline IDs to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-pipeline-id.

—buildkite-pipeline-slug <slug>

Buildkite pipeline slugs to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-pipeline-slug.

—buildkite-repository <repo>

Buildkite repositories to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-repository.

—buildkite-branch <name>

Buildkite branches to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-branch.

—buildkite-job-name <name>

Buildkite job names to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-job-name.

—buildkite-job-state <state>

Buildkite job states to include in the report. Repeatable. Cannot be passed together with --exclude-buildkite-job-state.

—exclude-branch <name>

GitHub branch(es) to exclude from the report. Repeatable. Cannot be passed together with --branch.

—exclude-jobname <name>

GitHub job name(s) to exclude from the report. Repeatable. Cannot be passed together with --jobname.

—exclude-platform <platform>

Platform(s) to exclude from the report (e.g. linux/amd64, linux/arm64). Repeatable. Cannot be passed together with --platform.

—exclude-profile <profile>

Runner profile(s) to exclude from the report. Repeatable. Cannot be passed together with --profile.

—exclude-purpose <purpose>

Instance purpose(s) to exclude from the report. Repeatable. Cannot be passed together with --purpose.

—exclude-repository <repo>

GitHub repository (or repositories) to exclude from the report. Repeatable. Cannot be passed together with --repository.

—exclude-shape <shape>

Instance shape(s) to exclude from the report. Repeatable. Cannot be passed together with --shape.

—exclude-workflow <name>

GitHub workflow(s) to exclude from the report. Repeatable. Cannot be passed together with --workflow.

—exclude-buildkite-org-id <id>

Buildkite organization IDs to exclude from the report. Repeatable. Cannot be passed together with --buildkite-org-id.

—exclude-buildkite-pipeline-id <id>

Buildkite pipeline IDs to exclude from the report. Repeatable. Cannot be passed together with --buildkite-pipeline-id.

—exclude-buildkite-pipeline-slug <slug>

Buildkite pipeline slugs to exclude from the report. Repeatable. Cannot be passed together with --buildkite-pipeline-slug.

—exclude-buildkite-repository <repo>

Buildkite repositories to exclude from the report. Repeatable. Cannot be passed together with --buildkite-repository.

—exclude-buildkite-branch <name>

Buildkite branches to exclude from the report. Repeatable. Cannot be passed together with --buildkite-branch.

—exclude-buildkite-job-name <name>

Buildkite job names to exclude from the report. Repeatable. Cannot be passed together with --buildkite-job-name.

—exclude-buildkite-job-state <state>

Buildkite job states to exclude from the report. Repeatable. Cannot be passed together with --buildkite-job-state. These --exclude-* flags mirror their include counterparts above and form a consistent include/exclude filter family across the report’s dimensions.

​Usage

​Example

​Options

​—start <time>

​—end <time>

​—out <path>

​—repository <repo>

​—workflow <name>

​—jobname <name>

​—branch <name>

​—platform <platform>

​—shape <shape>

​—purpose <purpose>

​—profile <profile>

​—buildkite-org-id <id>

​—buildkite-pipeline-id <id>

​—buildkite-pipeline-slug <slug>

​—buildkite-repository <repo>

​—buildkite-branch <name>

​—buildkite-job-name <name>

​—buildkite-job-state <state>

​—exclude-branch <name>

​—exclude-jobname <name>

​—exclude-platform <platform>

​—exclude-profile <profile>

​—exclude-purpose <purpose>

​—exclude-repository <repo>

​—exclude-shape <shape>

​—exclude-workflow <name>

​—exclude-buildkite-org-id <id>

​—exclude-buildkite-pipeline-id <id>

​—exclude-buildkite-pipeline-slug <slug>

​—exclude-buildkite-repository <repo>

​—exclude-buildkite-branch <name>

​—exclude-buildkite-job-name <name>

​—exclude-buildkite-job-state <state>