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

# 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`
* `github_profile`, `github_repository`, `github_branch`, `github_job_conclusion`

## Usage

```bash theme={null}
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:

```bash theme={null}
nsc instance report --start 2026-05-11T11:00:00Z --out -
```

```text nocopy Output theme={null}
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,github_profile,github_repository,github_branch,github_job_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,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,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,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,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,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,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

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

<h3 id="--start-time">
  \--start \<time>
</h3>

Start time of the report. Required.

<h3 id="--end-time">
  \--end \<time>
</h3>

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

<h3 id="--out-path">
  \--out \<path>
</h3>

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

<h3 id="--repository-repo">
  \--repository \<repo>
</h3>

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

<h3 id="--workflow-name">
  \--workflow \<name>
</h3>

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

<h3 id="--jobname-name">
  \--jobname \<name>
</h3>

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

<h3 id="--branch-name">
  \--branch \<name>
</h3>

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

<h3 id="--platform-platform">
  \--platform \<platform>
</h3>

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

<h3 id="--shape-shape">
  \--shape \<shape>
</h3>

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

<h3 id="--purpose-purpose">
  \--purpose \<purpose>
</h3>

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

<h3 id="--profile-profile">
  \--profile \<profile>
</h3>

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

<h3 id="--exclude-branch-name">
  \--exclude-branch \<name>
</h3>

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

<h3 id="--exclude-jobname-name">
  \--exclude-jobname \<name>
</h3>

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

<h3 id="--exclude-platform-platform">
  \--exclude-platform \<platform>
</h3>

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

<h3 id="--exclude-profile-profile">
  \--exclude-profile \<profile>
</h3>

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

<h3 id="--exclude-purpose-purpose">
  \--exclude-purpose \<purpose>
</h3>

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

<h3 id="--exclude-repository-repo">
  \--exclude-repository \<repo>
</h3>

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

<h3 id="--exclude-shape-shape">
  \--exclude-shape \<shape>
</h3>

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

<h3 id="--exclude-workflow-name">
  \--exclude-workflow \<name>
</h3>

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

These `--exclude-*` flags mirror their include counterparts above and form a
consistent include/exclude filter family across the report's dimensions.