Skip to content
Nodus
Blog

Request a dedicated interruptible node

POST
/v1/spot/nodes
 
curl --request POST \
  --url https://example.com/v1/spot/nodes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "gpu": "h200x8", "idempotency_key": "example", "local_wait_s": 1, "max_price_per_node_hr": 1, "placement": "local_first", "providers": [ "example" ], "regions": [ "example" ], "ssh_public_keys": [ "example" ], "workspace_id": "example", "workspace_slot": "example" }'

Reuse the same Idempotency-Key for every retry. A matching provisioning node is reused when no key is supplied. A preempted node releases its key. A failed node with end_reason capacity_unavailable releases its key only after confirmed cleanup, then returns retry_after seconds before another attempt. No-capacity responses create no node. Billing begins when SSH is ready.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
Nodus-Org
string

Organization to select with a user token; API keys are already scoped.

Idempotency-Key
string
<= 255 characters

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media type application/json
object
gpu
required
string
Allowed values: h200x8 h100x8 h200x1 h100x1 mi300x8
idempotency_key
string
<= 255 characters
local_wait_s
integer format: int64
<= 900
max_price_per_node_hr
number format: double
placement
string
Allowed values: local_first local_only cheapest
providers
Array<string> | null
regions
Array<string> | null
ssh_public_keys
Array<string> | null
workspace_id
string
workspace_slot
string
<= 32 characters

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

OK

Media type application/json
object
billed_seconds
required
integer format: int64
billing_warning
string
cleaned_at
string format: date-time
cost_so_far
required
number format: double
created_at
required
string format: date-time
end_reason
string
ended_at
required
string | null format: date-time
gpu
required
string
id
required
string
ip
required
string
price_per_node_hr
required
number format: double
provider
required
string
ready_at
required
string | null format: date-time
region
required
string
region_class
string
region_name
string
release_at
string format: date-time
retry_after
integer format: int64
ssh_command
string
ssh_port
required
integer format: int64
ssh_user
required
string
started_at
required
string | null format: date-time
startup_failure_code
string
Allowed values: capacity_unavailable
startup_failure_message
string
status
required
string
Allowed values: provisioning running preempted terminating terminated failed
workspace_id
string
workspace_slot
string
Example 
{
  "startup_failure_code": "capacity_unavailable",
  "status": "provisioning"
}

400

Section titled “ 400 ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}

402

Section titled “ 402 ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}

409

Section titled “ 409 ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}

429

Section titled “ 429 ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}

503

Section titled “ 503 ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}

default

Section titled “ default ”

Spot error or platform authentication failure

Media type application/json
object
current_price
number format: double
error
required
string
message
string
retry_after
integer format: int64
Example generated 
{
  "current_price": 1,
  "error": "example",
  "message": "example",
  "retry_after": 1
}