Get guest agent status or command output
GET /api/v2/vps/{id}/agent/exec
Without pid, says whether commands can run inside the VPS through the QEMU Guest Agent. available is false when the VPS is stopped or the agent does not answer. reason then says which. With pid, returns the output of a command started with POST /api/v2/vps/{id}/agent/exec. Poll it until exited is true. A VPS that is still being set up returns 409 vps_not_ready.
Authentication: An API key with the scope read:vm. Also write:vm: only when the query sets pid, to read command output. About keys and scopes
Request
Path parameters
idstringrequiredThe VPS ID (
vps_…).Query parameters
pidintegerProcess ID from the
POST /api/v2/vps/{id}/agent/exec response. Omit it to check whether commands can run.Example
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/agent/exec" \ -H "Authorization: Bearer $HOSTUP_API_KEY"Responses
200 The agent status without pid. The command output with pid.
{ "available": true, "reason": null, "vmRunning": true}{ "pid": 4242, "exited": true, "exitCode": 0, "stdout": "Linux app-01 6.8.0-31-generic x86_64 GNU/Linux\n", "stderr": ""}Response fields
availablebooleanTrue when commands can be run inside the VPS through the QEMU Guest Agent.
reasonstring or nullWhy commands cannot be run, when
available is false.vmRunningbooleanTrue when the VPS is running. Use
available to decide whether you can run a command.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |