Skip to main content

Async operations

Some actions take longer than a single HTTP response cycle: server rebuilds, snapshot creation/restore, PTR updates on certain backends. These return 202 Accepted with an Operation body and a Location header pointing at the operation resource.

The Operation resource​

{
  "id":           "op_01HRZ5K3P9X2W6V8M1C4Y7B0A2",
  "type":         "server.rebuild",
  "status":       "queued",
  "target":       { "type": "server", "id": "srv_abc123" },
  "progress":     null,
  "error":        null,
  "result":       null,
  "created_at":   "2026-05-21T14:30:00Z",
  "started_at":   null,
  "completed_at": null
}

status is one of: queued, running, succeeded, failed, cancelled.

Polling​

while true; do
  STATUS=$(curl -s https://api.vps-server.host/v1/operations/op_… \
    -H "Authorization: Bearer $PAT" | jq -r .status)
  echo "Status: $STATUS"
  [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]] && break
  sleep 3
done

Prefer webhooks over polling

Subscribe to operation.succeeded and operation.failed events instead — you'll get the final state pushed within seconds of completion. See Webhooks.

CLI helper​

The CLI has a built-in wait that polls for you:

vpsctl servers rebuild srv_abc123 --image ubuntu-24.04 --wait

Equivalent to issuing the request, parsing the operation id, and polling until terminal state.