---
title: Using placement groups with the API
description: This page shows you how to use placement groups on Instances using the Scaleway API
tags: compute placement-group server api instance
dates:
  validation: 2025-08-19
---
import Requirements from '@macros/iam/requirements.mdx'


Placement groups allow you to group your Instances.

You can choose between two operating modes: `max_availability`, which ensures that Instances of a group do not run on the same underlying hardware, and `low_latency`, which brings Instances closer together to achieve higher network throughput.

If you prefer a visual environment, discover [how to manage placement groups from the Scaleway console](/instances/how-to/use-placement-groups/).

<Requirements />

- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization

## Understanding placement groups

Placement groups work for all Instance ranges in the same Availability Zone without any architecture or type distinction. It means that all virtualized Instances ranges can be part of the same placement group. However, they are not compatible with Elastic Metal servers.

A placement group is composed of three mandatory fields:
- Name,
- Policy type,
- Policy mode.

**Name** is a free text field.

### Policy types

The policy type enables the choice of placement behavior for underlying Instances. It can be set to either `low_latency` or `max_availability`.

The low latency policy groups your Instances on the nearest hardware and limits network latency, allowing the highest network throughput between servers. At best, Instances will be placed on the same hypervisor.

The maximum availability policy spreads the Instances on far-away hypervisors as much as possible. It will limit the impact in case of hardware failure. For this policy, the Instances may be placed anywhere in the same Availability Zone.

### Policy modes

The policy mode selects the Instance's allocation behavior if the placement constraint cannot be respected. Policy mode can be set to either `optional` or `enforced`.

When the policy mode is set to optional then failing to respect the placement policy still allocates the server. When the policy mode is set to enforced then failing to respect the placement policy results in not allocating the server.

## Checking a group status

When several Instances are part of the same placement group, it is possible to query the full group status and then check the field `policy_respected`. This field indicates if the selected policy is respected or not. It returns `true` if the policy is respected, and `false` otherwise.

To get the placement information for a single server, query its server object. In the result, check the field `placement_group`. Likewise, it will be true if the placement is respected or false if it is not.

## Creating a placement group

As a practical application, we will see how to set up two Instances that should never run on the same hardware. To do so, we will create a `max_availability`type placement group with the `enforced` policy.

First, let us create the placement group with the appropriate `policy_type` and `policy_mode` fields:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X POST \
	-d '{"name": "cc-test", "policy_mode": "optional", "policy_type": "max_availability", "organization": "c2d2fe22-6b5a-4f09-abae-cb1d633f1533"}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/
```

A query to the placement group prints the current operation mode of the group:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4
{
  "placement_group": {
    "name": "cc-test",
    "policy_mode": "enforced",
    "policy_type": "max_availability",
    "organization": "c2d2fe22-6b5a-4f09-abae-cb1d633f1533",
    "policy_respected": true,
    "id": "ae5c1189-f421-4285-988b-80d29267ddc4"
  }
```

The `policy_respected` field is set to `true` as there is no server in the group at the moment.

To list Instances that belong to the group, use the `/placement_groups/*/servers` API endpoint:


```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers
{
  "servers": []
}
```

Our group is empty at the moment, so this is perfectly normal.

## Adding multiple existing Instances to a placement group

Once a placement group is created, you can add existing Instances in it. To do so, just call a PUT method on the `/placement_groups/*/servers` endpoint.

Before adding Instances to a group, ensure that they are all powered off. The placement procedure cannot work with a running server.

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	-X PUT \
	-d '{"servers": ["a3505194-b875-4bda-87c0-058466a6ea6d", "dab279bc-aa4d-4ba1-841c-ba04cc23eb00"]}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4
{
  "servers": [
    {
      "policy_respected": true,
      "id": "a3505194-b875-4bda-87c0-058466a6ea6d",
      "name": "elated-lamport"
    },
    {
      "policy_respected": true,
      "id": "dab279bc-aa4d-4ba1-841c-ba04cc23eb00",
      "name": "elegant-brown"
    }
  ]
}
```

The group now contains the two servers. If one of the servers was running, the API would have returned the error:

```
{
  "message": "One or more servers are invalid",
  "type": "invalid_request_error"
}
```

## Adding a single Instance to a placement group

A single Instance can also be directly added to a placement group. Again, the server must be off before doing so:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X PATCH -d '{"placement_group": "ae5c1189-f421-4285-988b-80d29267ddc4"}'
	\
	https://api.scaleway.com/instance/v1/zones/fr-par-1/servers/a3505194-b875-4bda-87c0-058466a6ea6d
```

In addition, an Instance can be created directly into a placement group by filing the `placement_group` field in the server creation API call.

## Removing an Instance from a placement group

An Instance, running or stopped, can be removed at any time from a placement group by setting its `placement_group` property to `null`:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	-X PATCH -d '{"placement_group": null}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/servers/dab279bc-aa4d-4ba1-841c-ba04cc23eb00
```

Remember that the Instance must be archived to be made part of a group so be
careful.


After that call, we only have one server left in our group:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers
{
  "servers": [
    {
      "policy_respected": true,
      "id": "a3505194-b875-4bda-87c0-058466a6ea6d",
      "name": "elated-lamport"
    }
  ]
}
```

It is also possible to remove all Instances from a placement group with a DELETE call on the API endpoint `/placement_groups/*/servers`:

```
curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X DELETE \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers

```

We hope that placement groups will help you build more performant and more reliable systems with Scaleway's products.

For more information and to see the full capabilities of placement groups, refer to the [full API documentation](https://www.scaleway.com/en/developers/api/instances/#path-placement-groups).

Remember that a placement group will work only according to the following rules:
- Instances must be in the same Availability Zone,
- An Instance can be in only one group at a time,
- A running Instance cannot be modified and should be archived.