Getting started with the Autoscaling Groups API

Reviewed on July 30, 2026

Autoscaling Groups adjust the number of Instances in a group automatically, based on scaling policies you define. A scaling action (scale-out or scale-in) triggers when a monitored metric, gathered through Cockpit, such as RAM or CPU usage, crosses the configured threshold. When a Load Balancer is attached to the group, Scaleway updates it automatically on each scaling action, so that connections stay distributed correctly among the active Instances. You can also configure the group to replace Instances that the Load Balancer marks as unhealthy.

Autoscaling Groups help you maintain application performance and control costs: the group scales up during peak traffic and scales down when demand decreases, without manual intervention.

This guide takes you from setup to your first working Autoscaling Group. You create an Instance template, launch an Autoscaling Group, and verify that scale-out, scale-in, and auto-healing behave as expected.

Important

The Autoscaling Groups API is in Private Beta. Submit your request for Beta access before following this guide.

Before you start

A Scaleway account logged into the console
Beta access to the Autoscaling Groups Private Beta
A Scaleway Project to work in
A terminal with curl and/or CLI installed
jq installed, to parse JSON responses (optional but recommended)

Get your API credentials

In the Console, go to Identity and Access Management > API Keys.
Click Generate API Key.
Copy the secret key. It is displayed only once.
In Organization > Project, copy your Project ID.

Make sure your API key has the required permissions:

InstancesFullAccess - Create templates and manage Instances.
LoadBalancersFullAccess - Link autoscaling groups to Load Balancers.
PrivateNetworksFullAccess - Attach Instances to Private Networks.

Set your environment variables

Open a terminal and set the following variables, replacing the placeholders with your own values:

export SCW_SECRET_KEY="<YOUR_API_SECRET_KEY>"
export SCW_PROJECT_ID="<YOUR_PROJECT_ID>"
export SCW_DEFAULT_ZONE="fr-par-1"
export SCW_DEFAULT_REGION="fr-par"

Create the required resources

Create a Load Balancer:

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs" \
  -d '{
    "name": "autoscaling-lb",
    "project_id": "'"$SCW_PROJECT_ID"'"
  }'

Save the id value from the response as LOAD_BALANCER_ID.

Create a backend for the Load Balancer. The server_ip list stays empty for now: the Autoscaling Group attaches Instances to it automatically as it scales.

LOAD_BALANCER_ID="<YOUR_LOAD_BALANCER_ID>"
 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/$LOAD_BALANCER_ID/backends" \
  -d '{
    "name": "autoscaling-backend",
    "forward_port": 80,
    "forward_port_algorithm": "roundrobin",
    "forward_protocol": "tcp",
    "health_check": {
      "check_delay": 2000,
      "check_max_retries": 3,
      "check_timeout": 1000,
      "port": 80,
      "tcp_config": {}
    },
    "server_ip": []
  }'

Save the id value from the response as BACKEND_ID.

Create a Private Network:

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/vpc/v2/regions/$SCW_DEFAULT_REGION/private-networks" \
  -d '{
    "name": "autoscaling-pn",
    "project_id": "'"$SCW_PROJECT_ID"'"
  }'

Save the id value from the response as PRIVATE_NETWORK_ID.

Get started with your Autoscaling Group

Create an Instance template

An Instance template defines the configuration used for Instances created by the Autoscaling Group.

The following command creates an Instance template.

PRIVATE_NETWORK_ID="<YOUR_PRIVATE_NETWORK_ID>"

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/instance/v2alpha1/zones/$SCW_DEFAULT_ZONE/templates" \
  -d '{
    "name": "autoscaling-template",
    "server_type": "PLAY2-NANO",
    "volumes": [
        {
          "name": "boot volume",
          "image_label": "ubuntu_noble",
          "volume_type": "sbs"
        }
    ],
    "private_networks": [
        {
          "private_network_id": "'"$PRIVATE_NETWORK_ID"'"
        }
    ],
    "project_id": "'"$SCW_PROJECT_ID"'"
  }'

Save the id value from the response. This is your INSTANCE_TEMPLATE_ID.

Create the Autoscaling Group

The following command creates a group that scales between two and eight Instances, based on a CPU usage target of 30%.

INSTANCE_TEMPLATE_ID="<YOUR_TEMPLATE_ID_FROM_STEP_2>"
LOAD_BALANCER_ID="<YOUR_LOAD_BALANCER_ID>"
BACKEND_ID="<YOUR_BACKEND_ID>"
PRIVATE_NETWORK_ID="<YOUR_PRIVATE_NETWORK_ID>"

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/autoscaling/v1alpha2/zones/$SCW_DEFAULT_ZONE/groups" \
  -d '{
    "project_id": "'"$SCW_PROJECT_ID"'",
    "name": "test-autoscaling-group",
    "template_id": "'"$INSTANCE_TEMPLATE_ID"'",
    "scaling_policy_spec": {
      "minimum_size": 2,
      "maximum_size": 8,
      "cpu_target": {
        "target_avg_percent": 30
      }
    },
    "load_balancer_configuration_spec":{
      "load_balancer_id": "'"$LOAD_BALANCER_ID"'",
      "auto_healing": {
        "enabled": true,
        "grace_period": "300s"
      },
      "backends": [
        {
          "backend_id": "'"$BACKEND_ID"'",
          "address_family": "ipv4",
          "private_network_id": "'"$PRIVATE_NETWORK_ID"'"
        }
      ]
    }
  }'

Save the group id value from the response. This is your AUTOSCALING_GROUP_ID.

Monitor your Autoscaling Group

Beyond the scaling events above, the following requests are available at any time to check on your group.

Get Autoscaling Group logs

Retrieve all scaling activities and events for the group:

AUTOSCALING_GROUP_ID="<YOUR_GROUP_ID>"

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/autoscaling/v1alpha2/zones/$SCW_DEFAULT_ZONE/logs?group_id=$AUTOSCALING_GROUP_ID"

The following log messages indicate the corresponding scaling activity:

Scaling event: added X instance(s): a scale-out event occurred
Scaling event: removed X instance(s): a scale-in event occurred
Auto-healing: replacing unhealthy instance: auto-healing was triggered

Check the current state of your group

# Get current instance count
curl -s -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/autoscaling/v1alpha2/zones/$SCW_DEFAULT_ZONE/servers?group_id=$AUTOSCALING_GROUP_ID" | jq '.servers | length'
 
# Get the last 5 log entries
curl -s -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/autoscaling/v1alpha2/zones/$SCW_DEFAULT_ZONE/logs?group_id=$AUTOSCALING_GROUP_ID" | jq '.logs[:5]'
 
# Get scaling alerts
curl -s -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/autoscaling/v1alpha2/zones/$SCW_DEFAULT_ZONE/alerts?group_id=$AUTOSCALING_GROUP_ID" | jq '.'

API endpoint reference

Action	Endpoint
Create template	`POST /instance/v2alpha1/zones/{zone}/templates`
Create group	`POST /autoscaling/v1alpha2/zones/{zone}/groups`
Get logs	`GET /autoscaling/v1alpha2/zones/{zone}/logs?group_id={id}`
Get alerts	`GET /autoscaling/v1alpha2/zones/{zone}/alerts?group_id={id}`
Get Instances	`GET /autoscaling/v1alpha2/zones/{zone}/servers?group_id={id}`

Troubleshooting

Error	Solution
`401 Unauthorized`	Check your `SCW_SECRET_KEY`
`403 Forbidden`	Verify your Beta access and Project permissions
`404 Not Found`	Check the zone and resource IDs
No scaling occurs	Wait 2 to 5 minutes, then check the CPU target threshold

Still need help?

Create a support ticket