---
title: "Submit Instance"
method: POST
path: "/instance"
tags: ["Instances"]
---

# Submit Instance

`POST /instance`

Submit a job to the queue or directly assign to a host.

If host_id is provided (marketplace launch), the job is assigned directly
to that host and container start is attempted immediately — unless the
transactional scheduler owns the job (canary/active partition), in which
case the pin is recorded and placement/start stay with the claim→reserve
path. Otherwise the job is queued and process_queue runs to find a host.

## Request body

- JobIn
  - `name` string, required
  - `vram_needed_gb` number
  - `priority` integer
  - `tier` string, nullable
  - `num_gpus` integer
  - `host_id` string, nullable
  - `gpu_model` string, nullable
  - `nfs_server` string, nullable
  - `nfs_path` string, nullable
  - `nfs_mount_point` string, nullable
  - `image` string, nullable
  - `interactive` boolean
  - `command` string, nullable
  - `ssh_port` integer
  - `pricing_mode` 'on_demand' | 'spot'
  - `placement_preference` PlacementPreferenceBody — A stated placement preference on a launch — the same shape `/api/v1/placements/evaluate` takes, so what a user previewed is what they can submit. Bounds mirror `routes.action_plans.PlacementPreferenceIn` deliberately: one validator disagreeing with another is how a request that previewed fine gets refused at launch. The database CHECKs (migration 115) sit beneath both.
    - `min_uptime_pct` number, nullable
    - `min_tier` string, nullable
    - `require_verified` boolean
    - `max_premium_pct` number, nullable
  - `volume_ids` string[], nullable
  - `encrypted_workspace` boolean
  - `init_script` string, nullable
  - `git_repo` string, nullable
  - `auto_launch` string[], nullable
  - `exposed_ports` integer[], nullable
  - `template_image_id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

> 22 revisions in range; 2 could not be searched.

- **2026-06-09** `9e47c8093db6` — 1 warning, 1 info
  - removed the request property `max_bid`
  - added the new optional request property `pricing_mode`
- **2026-06-08** `cbe3ad94235c` — 7 info
  - added the new optional request property `auto_launch`
  - added the new optional request property `encrypted_workspace`
  - added the new optional request property `exposed_ports`
  - added the new optional request property `git_repo`
  - …3 more
- **2026-04-10** `95960849edcd` — 1 info
  - added the new optional request property `max_bid`
- **2026-04-03** `74dc97653bc3` — 1 warning, 4 info
  - the `vram_needed_gb` request property's min was set to `0.00`
  - added the new optional request property `gpu_model`
  - added the new optional request property `host_id`
  - the request property `vram_needed_gb` became optional
  - …1 more
- **2026-04-01** `526c3dd3d9d7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/aabiro/apis/xcelsior/changes/instance/post.md)

---

[API](https://skmtc.dev/aabiro/apis/xcelsior.md) · [All operations](https://skmtc.dev/aabiro/apis/xcelsior/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aabiro/xcelsior/revisions/32211b6f9d65/schema)