--- title: "List saved research workspaces" method: GET path: "/v1/research-workspaces" tags: ["Research workspaces"] --- # List saved research workspaces `GET /v1/research-workspaces` ## Request - Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin) - URL: `/v1/research-workspaces` - Auth: HTTP bearer Returns a page owned by the authenticated account, newest first. The default kind workspace excludes standalone instances. Use kind instance for standalone instances. Cursors are bound to the selected kind. The default and maximum page size are 100. Includes compute-session costs, separate retained-storage costs and tool readiness. Continue with next_cursor until it is empty. Pages reflect current records and do not form a snapshot across concurrent changes. ## Query parameters - `kind` 'workspace' | 'instance' - `limit` integer - `cursor` string ## Response `200` Workspace list - ResearchWorkspaceList - `workspaces` ResearchWorkspace[], required - `id` string, required - `name` string, required - `size_gb` number, required - `holder_id` string, nullable, required - `saved_at` string, date-time, nullable, required - `expired_at` string, date-time, nullable: Time the tenant retention policy expired saved workspace state. The namespace remains listed. - `cleanup_pending` boolean: Expired workspace objects still require cleanup. An empty namespace can be reused after cleanup settles. - `stored_bytes` integer, nullable, required - `last_error` string, required - `saving_for_termination` boolean, required - `billing_status` 'disabled_no_approved_storage_rate' | 'metered_subject_to_account_limits' | 'included_workspace_storage' | 'account_workspace_storage' | 'ephemeral_instance', required: Storage billing policy for this record. ephemeral_instance has no saved storage or storage charge. Its compute session is billed separately. - `configuration` ResearchWorkspaceConfiguration, required - `kind` '' | 'workspace' | 'instance': Omission or an empty value preserves a saved workspace. instance creates standalone compute with SSH and local disk only. The kind cannot change after creation. An existing SSH workspace remains a workspace. - `name` string, required: Unique workspace name within the authenticated account. The names . and .. are not accepted. - `environment` 'pytorch-cuda' | 'pytorch-rocm' | 'pytorch-cpu' | 'custom-cuda' | 'custom-rocm' | 'custom-cpu', required: Qualified software environment for NVIDIA, AMD or CPU compute. Custom environments require a team-visible runtime_id. - `runtime_id` string: Optional immutable image identity from capabilities.runtimes. Selects the workspace Linux distribution and software. Must match environment and remain qualified and visible to the team. Omission preserves the existing managed environment. The selected runtime cannot be changed when editing a saved project. - `gpu` string, required: GPU model, not a supplier SKU. Use an empty string for CPU instances. Launch requires an exact qualified configuration and eligible capacity. - `gpu_count` 0 | 1 | 2 | 4 | 8, required: Exact GPU count on one machine. Use zero for CPU instances. These accepted request values do not establish hardware qualification or current availability. - `gpu_memory_gb` number, required: Minimum required memory per GPU in GB, not the sum across devices. Positive for GPU instances and zero for CPU instances. - `compute_class` 'accelerator' | 'vm': Omission retains GPU execution. vm requests a CPU-only workspace and requires capabilities.cpu_instances, a CPU environment, empty gpu, zero gpu_count and zero gpu_memory_gb. - `gpu_form_factor` '' | 'pcie' | 'sxm' | 'nvl': Optional required GPU form factor. Omission permits any form factor. Requires direct workspace compute and cannot be set for CPU instances. A selected form factor is enforced during quoting and placement. - `vcpus` integer: Minimum vCPUs on a GPU machine. Omission or zero keeps its included resources. CPU instances require exactly 2, 4, 8, 16 or 32 vCPUs. - `host_memory_gb` number: Minimum system RAM in GB, separate from GPU memory. Omission or zero keeps included RAM on GPU machines. CPU instances require a positive value. Custom RAM requires direct workspace compute. - `disk_gb` union: Runtime storage in decimal GB. Omission or zero preserves the existing 80 GB floor. Explicit sizes from 80 through 2048 are accepted. This is separate from the saved project capacity in size_gb. Restoring saved files can require additional allocation. - 0 - integer - `size_gb` number: Instances require zero and have no saved project storage. For workspaces, omit to use the deployment capacity, or send a positive capacity within capabilities.storage_limit_bytes. With storage_policy_version included-10gb-v1 or r2-standard-10gb-account-v1, send exactly 10 for the 10,000,000,000-byte per-workspace capacity. The account policy shares its free allowance across workspaces. Other deployments use GiB and their displayed capacity limit. - `ssh_authorized_key` string: Plain SSH public keys, one per line, up to 20. Private keys, certificates and authorized_keys options are rejected. Machines also admit every SSH key saved by a team member. Instances and SSH-only workspaces on direct compute may omit this field. SSH is then unavailable until a key exists, and a running machine admits newly saved team keys within seconds. Deployments without direct compute still require it and return 400 invalid_ssh_authorized_key when it is missing. - `pending_upload` WorkspacePendingUpload, required: An unfinished customer folder upload. Use its ID with the existing transfer status, segment, finalize and discard routes. Available from any authenticated browser for this account. Reselecting files requires the same manifest commitment. Runtime saves are excluded. - `id` string, uuid, required - `workspace_id` string, required - `state` 'uploading' | 'queued' | 'verifying', required - `base_revision` integer, required - `manifest_sha256` string, required - `manifest_bytes` integer, required - `configuration_revision` string, required: Saved configuration identity. Send this observed value when editing settings. Independent from the saved-file revision. - `storage_revision` integer, required: Current saved-file revision used to guard a stopped-workspace replacement. - `storage_policy_version` string, required: Storage policy recorded for this workspace. Transfer endpoints require a compatible versioned storage policy on the workspace and deployment. - `session` Sandbox, required - `id` string, required - `state` 'creating' | 'ready' | 'running' | 'idle' | 'suspended' | 'resuming' | 'recovering' | 'terminated' | 'failed' | 'freezing' | 'frozen', required - `envelope` SandboxEnvelope, required - `bootstrap` SandboxBootstrap: Preview repository bootstrap. Requires github.com in the egress allowlist. Checkout is placed in /workspace. The installation credential is never supplied to customer processes. - `repo` string, required: Connected GitHub repository as owner/name. Credentials and URLs are not accepted. - `ref` string: Optional branch name or refs/tags/name. Defaults to the repository default branch. - `setup` string: Shell setup command recorded as a sandbox execution. A managed template requires successful setup before customer commands. Legacy images retain their existing warning behavior. - `dotfiles` string: Optional connected GitHub dotfiles repository as owner/name. Its install.sh runs before setup. - `continuity` object, required - `from_snapshot` string - `lifecycle` SandboxLifecycle, required - `idle_timeout_s` integer: Idle seconds before the configured action. - `max_lifetime_s` integer: Maximum sandbox lifetime in seconds. - `on_idle` 'suspend' | 'terminate': Action after the idle timeout. - `name` string - `outcome` SandboxOutcome, required - `max_cost_usd` number: Deprecated compatibility field. Customer spending limits are not enforced. - `complete_by` string, date-time: Optional RFC3339 deadline for the sandbox. - `policy` SandboxPolicy, required - `data_regions` string[]: Allowed placement regions. Empty or omitted imposes no region filter. - `network` 'deny' | 'allowlist': Outbound network policy. - `egress_allow` string[]: Exact DNS hostnames allowed when network is allowlist. - `secret_refs` string[]: Secret names or sec_ IDs pinned at admission and delivered as NODUS_SECRET_. Rotation, revocation and recovery preserve the admitted version. - `profile` string: Historical profile retained on previously admitted sandboxes. New sandbox requests cannot select a profile. - `requirements` object, required - `reservation` object, required - `secrets` string[]: Tenant secret names bound to current versions at boot. The NODUS_ prefix is reserved. Values are available to commands as environment variables and files in NODUS_SECRETS_DIR. - `service` SandboxService - `command` string[], required - `port` integer, required: Guest loopback HTTP port. Port 18080 is reserved. - `health_path` string, required: Absolute HTTP health path. Successful 2xx health response is required before serving requests. - `source` object, required - `image` string, required - `asset_id` string - `cache` boolean: Opt in to verified image layer caching within this team and selected execution region. Retained storage stays attributed to the first materializing sandbox at the configured workspace storage rate. Cache misses use the image registry. - `stuck_after_s` integer: Alert after an active command produces no output for this many seconds. Defaults to 1800. Alerts do not stop the command. - `workspace` WorkspaceSelection - `name` string, required - `mount` string: Dedicated top-level directory. System directories cannot be used. - `connections` string[]: One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode. - `created_at` string, date-time, required - `updated_at` string, date-time, required - `last_activity_at` string, date-time, required - `terminal_at` string, date-time, nullable - `cost_usd` number, required: Customer cost recorded for this sandbox. - `charge_state` 'estimated' | 'final': Present for metered sandboxes. A terminal sandbox remains estimated while required cost records are unavailable. Show Finalizing cost until final. Historical contracts omit this field. - `final_charge_usd` number: Immutable aggregate lifetime compute charge once charge_state is final. This amount is independent of current-month readings and excludes ongoing retained-file usage. Retaining files can continue to incur separate usage charges after compute is final. Omitted while the compute cost is finalizing. - `network_usage` object: Last reported cumulative proxied HTTP and TLS stream bytes across sandbox generations. A lost host can leave its final unreported bytes unknown. These counters do not determine customer charges. - `sent_bytes` integer, required - `received_bytes` integer, required - `url` string, uri, required: Console URL for this sandbox. - `failure` object: Recorded cause and recovery guidance for a failed sandbox. Omitted for other states. - `code` string, required - `message` string, required - `fix` string, required - `warnings` string[]: Nonfatal warnings, including bootstrap_failed when the setup command fails. - `setup_state` string - `setup_failure` string - `last_successful_save_at` string, date-time: Last verified nonempty saved project. Absence does not imply saved application progress. - `startup` SandboxStartup: Measured startup stages. Missing durations are unobserved. Overlapping durations must not be added into elapsed latency. - `stage` string - `acquisition_ms` integer - `image_preparation_ms` integer - `project_download_ms` integer - `project_materialization_ms` integer - `checkpoint_download_ms` integer - `checkpoint_restore_ms` integer - `setup_ms` integer - `driver_start_ms` integer - `image_cache_reads` integer - `image_cache_hits` integer - `project_prefetched` boolean - `checkpoint_prefetched` boolean - `warm_claimed` boolean - `warm_miss_reason` string - `started_at` string, date-time: First observed tool readiness for the current direct workspace compute session. Absent while starting and on legacy sessions without this timestamp. This is separate from creation time and changes with a replacement session. - `meter` ResearchWorkspaceMeter, required: Lifetime charges for the current compute session, including platform fees and excluding retained workspace storage. Settled and unposted accrued amounts are consistent as of the same time. Values are for the whole machine and must not be multiplied by gpu_count. - `settled_usd` number, required: Posted compute and platform charges across this session's entire lifetime, including prior billing months. - `accruing_usd` number, required: Unposted compute and platform charges through as_of. - `accruing_rate_usd_hour` number, required: Current whole-node hourly charge rate. Zero when no charge is growing. - `total_now_usd` number, required: settled_usd plus accruing_usd at as_of. - `as_of` string, date-time, required - `compute_settled_usd` number, required - `platform_fee_settled_usd` number, required - `subscription_settled_usd` number, required: Zero for workspace compute sessions. - `storage_settled_usd` number: Zero for workspace compute sessions. Saved-file charges belong to the account meter. - `model_settled_usd` number: Zero for workspace compute sessions. Managed model charges belong to the account meter. - `shared_settled_usd` number: Zero for workspace compute sessions. Shared service charges belong to the account meter. - `compute_accruing_usd` number, required - `platform_fee_accruing_usd` number, required - `final_charge_usd` number: Immutable aggregate lifetime compute charge once the session has stopped and all required compute cost records are complete. Excludes saved-file storage, which can continue to incur separate usage charges. Omitted while finalizing. - `charge_state` 'estimated' | 'final': Present for metered compute sessions. Stopped sessions remain estimated while required cost records are unavailable. Historical contracts omit this field. - `state` 'stopped' | 'creating' | 'ready' | 'running' | 'idle' | 'suspended' | 'resuming' | 'recovering' | 'stopping' | 'failed' | 'freezing' | 'frozen', required: Workspace lifecycle view. stopping includes a pending final save or unconfirmed compute release. Tool access also requires its connections flag. - `status_message` string, required - `connections` object, required: Current tool readiness for the authorized compute session. Compute may continue to accrue charges while these flags are false. - `editor` boolean, required - `notebook` boolean, required - `ssh` boolean, required - `storage` ResearchWorkspaceStorage, required - `rate_usd_gib_month` number, required: Approved retained-storage rate in USD per GiB-month, separate from compute. Zero when storage billing is disabled. - `price_version` string, required: Approved storage price version, or an empty string when billing is disabled. - `retained_bytes` integer, required: Total retained storage for this workspace, including data needed to restore saved files. May exceed the latest save's stored_bytes. - `charged_usd` number, required: Lifetime posted storage charges for this workspace, not a compute-session charge. - `as_of` string, date-time, required - `next_cursor` string: Opaque continuation for this account and list. Empty when this page has no further records. ## Other responses - `default`: Authentication, rate limits and transient failures apply. ## Changes - **2026-10-01** `5805e96227f4`: 1 info - added the optional property `workspaces/items/allOf[subschema #2]/meter/oneOf[#/components/schemas/ResearchWorkspaceMeter]/shared_settled_usd` to the response with the `200` status - **2026-10-01** `ba84c74aeec8`: 4 breaking, 11 warning, 23 info - the response property `workspaces/items/allOf[subschema #2]/configuration/size_gb` became optional for the status `200` - the `workspaces/items/allOf[subschema #2]/configuration/size_gb` response property's min was decreased from `0.00` to `0.00` for the response status `200` - the `workspaces/items/allOf[subschema #2]/configuration/gpu` response property's minLength was decreased from `1` to `0` for the response status `200` - removed the required property `workspaces/items/allOf[subschema #2]/configuration/max_hours` from the response with the `200` status - …34 more - **2026-10-01** `544fef290a54`: 3 breaking, 18 warning, 15 info - removed 'else' subschema from the `workspaces/items/allOf[subschema #2]/configuration` response property for the status `200` - removed 'if' subschema from the `workspaces/items/allOf[subschema #2]/configuration` response property for the status `200` - removed 'then' subschema from the `workspaces/items/allOf[subschema #2]/configuration` response property for the status `200` - deleted the `query` request parameter `cursor` - …32 more - …earlier changes not shown [Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/research-workspaces/get.md) --- [API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)