Error

A valid request URL is required to generate request examples

{
  "spid": 3
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

operation

Spawn an additional subprocess inside a running instance

Starts a new process inside the VM that already hosts the named operation. Distinct from POST /instances, which spins up a VM: this endpoint requires a running operation (EXECUTING or ASSIGNED) and reuses the existing VM.

The body is an ExecSpec — process-execution fields only. VM-level concerns (image, hostname, resources_limits, files, timeout, disposable, preserve_env) are not accepted here; they were set when the parent operation was created.

The required permission follows the parent instance: SPAWN_DISPOSABLE when it was spawned with disposable=true, SPAWN otherwise.

On success the worker assigns a fresh spid (≥2; spid=1 is the main process spawned from metadata) and the response carries it in the body plus a Location header pointing at GET /operations/{operationId}/subprocesses/{spid} — the subprocess result reconstructed from its events.

POST

operations

{operationId}

subprocesses

Error

A valid request URL is required to generate request examples

{
  "spid": 3
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

IAM bearer token issued by the Nebius IAM service. Sent as Authorization: Bearer <iam-token>. Must be combined with the Project header (see IAMProjectHeader).

This is the recommended authentication scheme for new clients.

Project

string

header

required

Nebius project ID associated with the IAM token. Required together with IAMBearerAuth. Identifies the project context the request is scoped to.

Path Parameters

operationId

string<uuid>

required

The ID of the operation A UUID string

Example:

"12345678-9abc-baba-deda-0123456789ab"

Body

application/json

Process-execution surface shared between InstanceSpawnRequest (the main process) and POST /operations/{operationId}/subprocesses (additional subprocesses). VM-level concerns (image, hostname, resources_limits, files, timeout, disposable, preserve_env) live on InstanceSpawnRequest only.

command

string

required

The command to execute. Same semantics as in InstanceSpawnRequest.command — when shell=true it is a shell expression, otherwise a path to an executable.

Example:

"/bin/app"

args

string[]

Arguments to pass to the command if shell is set to false.

Example:

["arg1", "arg2"]

shell

boolean

default:false

Run command through a shell expression (args must be empty).

env

object | null

Environment variables to set in the child process.

Show child attributes

cwd

string

default:""

Working directory; empty string means image / server default.

Pattern: ^((/[^/]*)+/?)?$

uid

integer

default:0

User ID to run the process as.

Required range: x >= 0

gid

integer

default:0

Group ID to run the process as.

Required range: x >= 0

stdin

object

Bytes fed to the child's stdin — honored for both the main process and exec'd subprocesses. With close=false the pipe stays open and more data can be written via POST /operations/{operationId}/subprocesses/{spid}/stdin.

Show child attributes

truncate_output_at

integer

default:1048576

Maximum number of bytes of stdout / stderr to keep. Defaults to 1 MiB; capped at 10 MiB.

Example:

65535

Response

Created — subprocess started. Location references the new subprocess result.

spid

integer

required

Spawn id assigned by the worker.

Required range: x >= 2

Stream the operation event log via Server-Sent Events Result of one subprocess, reconstructed from its events

⌘I

API Documentation

Inference and Training

Sandboxes

Spawn an additional subprocess inside a running instance

Authorizations

Path Parameters

Body

Response