Skip to content

List placement group candidates

GET /api/v2/placement-groups/candidates

List your VPSes and whether each can join a placement group. Active, pending and suspended VPSes are listed. A VPS can be in one placement group at a time. available is false when it is already in one or cannot be placed right now. reason then says why.

Authentication: An API key with the scope read:vm. About keys and scopes

Example

GET /api/v2/placement-groups/candidates
curl "https://cloud.hostup.se/api/v2/placement-groups/candidates" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Your VPSes and whether each can join a group.

Response 200
{
"candidates": [
{
"id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "db-primary",
"instanceUrl": "/instance/vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"compatibilityKey": null,
"placementGroupId": "pg_01hxa3b4c5d6e7f8g9h0j1k2m3",
"available": false,
"reason": "This VPS is already in a placement group."
},
{
"id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m4",
"name": "db-replica",
"instanceUrl": "/instance/vps_01hxa3b4c5d6e7f8g9h0j1k2m4",
"compatibilityKey": null,
"placementGroupId": null,
"available": true,
"reason": null
}
]
}
Response fields
candidatesarray of object
idstring
The VPS ID (vps_…). Send it as vpsId when you add the VPS.
namestring
Hostname or label of the VPS.
instanceUrlstring
Path of the VPS page in the client area.
compatibilityKeystring or nulldeprecated
Deprecated. Always null.
placementGroupIdstring or null
The group the VPS is in (pg_…). null when it is in none.
availableboolean
true when the VPS can be added to a group now.
reasonstring or null
Why the VPS cannot be added. null when available is true.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.