---
title: "Submit an independent workload from this project"
method: POST
path: "/v1/research-workspaces/{id}/workloads"
tags: ["Research workspaces"]
---

# Submit an independent workload from this project

`POST /v1/research-workspaces/{id}/workloads`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/research-workspaces/{id}/workloads`
- Auth: HTTP bearer

Captures current project files from ready compute, or pins the last successful saved revision while stopped. The command uses that immutable project revision and the workspace environment image. Optional GPU overrides apply only to the submitted workload. Running workspace capture returns 409 workspace_save_pending until saving finishes. Source preparation returns 409 workspace_source_pending until its verified copy is ready. Saving has a 45-minute deadline. Each source preparation attempt has a 45-minute deadline, with up to three automatic attempts. Cleanup waits may extend total preparation. Console and SDK waiting pause local observation after 95 minutes by default while retaining the submission intent. Reuse the exact body and Idempotency-Key to check progress or retry an uncertain reply. Identical captured revisions reuse a source copy within the included account source pool. Exports exclude .nodus and .git. Regular files, empty directories and safe relative symbolic links within the project are preserved. Unsafe links and unsupported file types are rejected before admission. A 202 response means ordinary workload admission succeeded. It does not establish execution or completion. Later edits and stopping workspace compute do not stop an admitted workload. Both incur charges while running.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- WorkspaceWorkloadRequest
  - `command` string, required: Command run from the captured project directory through the environment shell. Whitespace-only commands, NUL characters and commands longer than 8192 UTF-8 bytes are rejected.
  - `budget_usd` number: Deprecated compatibility field. Customer spending limits are not enforced.
  - `gpu` string: Optional GPU model override. Omit or send an empty string to inherit the workspace configuration.
  - `gpu_count` 0 | 1 | 2 | 4 | 8: Exact GPUs on one machine. Omitted or zero inherits the workspace configuration.
  - `gpu_memory_gb` number: Memory per GPU in GB. Omitted or zero inherits the workspace configuration.

## Response `202`

Independent workload admitted or replayed

- SubmitResult
  - `id` string, required
  - `workload_id` string, required
  - `status` string, required
  - `revision` integer, required

## Other responses

- `409`: workspace_save_pending and workspace_source_pending request the same key and body again after Retry-After. workspace_source_quota requires freeing included source space through Assets and using a new submission key. workspace_capture_failed requires correcting the save failure and beginning a new submission. workspace_source_rejected requires correcting the project source and using a new submission key. workspace_source_failed requires resolving the reported preparation failure and using a new submission key after cleanup. workspace_source_removed means its reference was deleted and a new submission must prepare a new copy. workspace_no_saved_files requires adding project files. workspace_source_unavailable reports a source preparation failure. idempotency_conflict indicates a changed body for an existing key. Other state conflicts can also occur.
- `default`: 400 for invalid command or GPU configuration. 402 for payment or credit requirements. 404 for a workspace outside this account. 503 when submission is unavailable. Ordinary workload admission checks, authentication, rate limits and transient failures also apply.

## Changes

- **2026-10-01** `ba84c74aeec8`: 1 info
  - request property `budget_usd` deprecated
- **2026-10-01** `544fef290a54`: 1 warning, 1 info
  - the `budget_usd` request property's min was set to `0.00`
  - request property `budget_usd` reactivated
- **2026-09-27** `dcc58d93c2cb`: 1 info
  - request property `budget_usd` deprecated
- **2026-09-27** `90c4cb8514af`: 1 warning, 1 info
  - the `budget_usd` request property's min was set to `0.00`
  - request property `budget_usd` reactivated
- **2026-09-26** `fddd7d91a5a5`: 1 info
  - request property `budget_usd` deprecated

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/research-workspaces/:id/workloads/post.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)