Skip to content

List placement groups

GET /api/v2/placement-groups

List the placement groups in your account, newest first. A placement group keeps VPSes in different sets (a, b, c) on separate hardware. Each entry shows the group’s health and how many VPSes it holds. Get the members with GET /api/v2/placement-groups/{id}.

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

Example

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

Responses

200 Your placement groups.

Response 200
{
"placementGroups": [
{
"id": "pg_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "Production database",
"policy": "spread",
"health": "ok",
"needsAttention": false,
"memberCount": 3,
"createdAt": "2026-06-28T10:00:00.000Z",
"updatedAt": "2026-06-28T10:05:00.000Z"
}
]
}
Response fields
placementGroupsarray of object
idstring
The placement group ID (pg_…).
namestring
Name of the group.
policystring
Placement policy. Always spread. One of spread.
healthstring
ok: every set is apart. reconciling: a VPS is being moved. violation: VPSes from different sets share hardware. One of ok, reconciling, violation.
needsAttentionboolean
true when automatic separation could not finish. Check actions.canResolve.
memberCountinteger
Number of VPSes in the group.
createdAtstring
When the group was created.
updatedAtstring
When the group was last changed.

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.