Spot Instances API

This page collects the API endpoints dedicated to Spot Instances. For all other server operations (list, delete, actions, …) see Server.

Authentication via the X-APITOKEN: <token> header — see how to create an API Token.

Discounts are fractions

All discount fields (discount, spot_discount) are expressed as a fraction between 0 and 1 — for example 0.4 means 40%, not an integer percentage value.

Available spot plans

Lists the plans that have an active spot discount, filtered by the user profile's provider.

GET /api/v2/plans/spot

Response 200 — plan has the same shape as /plans, plus the discount field:

{
  "status": "ok",
  "plans": [
    {
      "plan": {
        "id": 17,
        "name": "ECS4",
        "hourly_price": 0.10,
        "montly_price": 72.0,
        "cpu": "4",
        "ram": "8",
        "disk": "80",
        "host_type": "ECS",
        "available_regions": [
          { "id": 3, "location": "it-fr2", "description": "Frosinone" },
          { "id": 5, "location": "it-mi1", "description": "Milano" }
        ]
      },
      "discount": 0.4
    }
  ]
}

Creation

To create a spot add the "spot": true field to the normal server creation body:

POST /api/v2/servers
{
  "plan": "ECS4",
  "image": "ubuntu-22.04",
  "location": "it-fr2",
  "spot": true
}

The response is identical to an on-demand create (action_id + server), with the spot node set in the server object. Constraints:

spot: true and reserved_plan are mutually exclusive → 400 (spot and reserved_plan are mutually exclusive);
if no spot discount is available for the requested plan → SpotPlanNotAvailable error.

Spot status

Returns the Spot Instance status. It also responds after the server has been terminated, because the status record survives deletion.

GET /api/v2/servers/<servername>/spot-status

Response 200:

{
  "server": "ec2-abc123",
  "status": "ok",
  "discount": 0.4,
  "notified_at": null,
  "terminate_at": null,
  "promoted_at": null
}

status: ok | terminating | terminated | promoted (see Termination and notice);
notified_at / terminate_at: null until reclaim starts; on notice they hold the notice moment and notified_at + 120s respectively;
promoted_at: null if the instance was never promoted.

Promotion

Promotes the spot to on-demand. Idempotent if the instance is already promoted.

PATCH /api/v2/servers/<servername>/spot-status
{
  "status": "promoted"
}

The endpoint also accepts PUT. The 200 response contains the updated spot record (same shape as Spot status). Outcomes:

Condition	Result
instance `ok`	`200` — promoted
instance already `promoted`	`200` — no effect (idempotent)
instance `terminating`	`400` — termination already scheduled
instance `terminated`	`400` — instance already terminated
server is not a spot	`404`

Availability

The plan availability endpoint exposes the spot fields for each plan/region:

GET /api/v2/plans/availables

spot_discount — plan discount as a fraction 0..1, or null if the plan is not spot-eligible;
spot_available — true if a spot is creatable in that region right now.