> ## 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 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](https://namespace.so/docs/solutions/github-actions/index.md) 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](https://namespace.so/docs/solutions/buildkite-agents/index.md) 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

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

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

The following example shows a GitHub Actions report:

```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,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

```text wrap Agent Prompt theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.