nsc instance report

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 job that triggered it.

The report 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)
  • 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

Usage

nsc instance report --start <time> [--end <time>] [--out <path>] [filters...]

--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 covering the last hour and writes it to stdout:

$ nsc instance report --start 2026-05-11T11:00:00Z --out -
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,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
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,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
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,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
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,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

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:

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> / --exclude-repository <repo>

GitHub repository (or repositories) to include or exclude. Repeatable. --repository and --exclude-repository cannot be combined.

--workflow <name> / --exclude-workflow <name>

GitHub workflow(s) to include or exclude. Repeatable.

--jobname <name> / --exclude-jobname <name>

GitHub job name(s) to include or exclude. Repeatable.

--branch <name> / --exclude-branch <name>

GitHub branch(es) to include or exclude. Repeatable.

--platform <platform> / --exclude-platform <platform>

Platform(s) to include or exclude (e.g. linux/amd64, linux/arm64). Repeatable.

--shape <shape> / --exclude-shape <shape>

Instance shape(s) to include or exclude. Repeatable.

--purpose <purpose> / --exclude-purpose <purpose>

Instance purpose(s) to include or exclude. Repeatable.

Last updated