Instances are computing units providing resources to run your applications on. Scaleway offers various Instance types including Virtual Instances and dedicated GPU Instances. Note: Instances can be referenced as "servers" in API endpoints.
List all Instances
List all Instances in a specified Availability Zone, e.g. fr-par-1.
path Parameters
zoneThe zone you want to target
query Parameters
per_pageA positive integer lower or equal to 100 to select the number of items to return.
pageA positive integer to choose the page to return.
organizationList only Instances of this Organization ID.
projectList only Instances of this Project ID.
nameFilter Instances by name (eg. "server1" will return "server100" and "server1" but not "foo").
private_ipList Instances by private_ip. (IP address)
without_ipList Instances that are not attached to a public IP.
with_ipList Instances by IP (both private_ip and public_ip are supported). (IP address)
commercial_typeList Instances of this commercial type.
stateList Instances in this state.
tagsList Instances with these exact tags (to filter with several tags, use commas to separate them).
private_networkList Instances in this Private Network.
orderDefine the order of the returned servers.
private_networksList Instances from the given Private Networks (use commas to separate them).
private_nic_mac_addressList Instances associated with the given private NIC MAC address.
serversList Instances from these server ids (use commas to separate them).
List all Instances › Responses
List of Instances.
Create an Instance
Create a new Instance of the specified commercial type in the specified zone. Pay attention to the volumes parameter, which takes an object which can be used in different ways to achieve different behaviors. Get more information in the Technical Information section of the introduction.
path Parameters
zoneThe zone you want to target
Create an Instance › Request Body
nameInstance name.
commercial_typeDefine the Instance commercial type (i.e. GP1-S).
dynamic_ip_requiredDefine if a dynamic IPv4 is required for the Instance.
By default, dynamic_ip_required is true, a dynamic ip is attached to the instance (if no flexible ip is already attached).
imageInstance image ID or label.
When an image label is used, it will be converted to the latest image available on the Marketplace.
By default, the selected local image will be the instance_sbs local image.
If an l_ssd volume is specified in the volumes argument, an instance_local local image will be selected instead.
Volumes attached to the server.
public_ipsA list of reserved IP IDs to attach to the Instance.
boot_typeBoot type to use.
projectInstance Project ID.
tagsInstance tags.
security_groupSecurity group ID.
placement_groupPlacement group ID if Instance must be part of a placement group.
admin_password_encryption_ssh_key_idUUID of the SSH RSA key that will be used to encrypt the initial admin password for OS requiring it. Mandatory for Windows OS. The public_key value of this key is used to encrypt the admin password.
protectedTrue to activate server protection option.
routed_ip_enabledIf true, configure the Instance so it uses the new routed IP mode.
enable_ipv6True if IPv6 is enabled on the server (deprecated and always False when routed_ip_enabled is True).
public_ipID of the reserved IP to attach to the Instance.
organizationInstance Organization ID.
Create an Instance › Responses
Get an Instance
Update an Instance
Update the Instance information, such as name, boot mode, or tags.
path Parameters
zoneThe zone you want to target
server_idUUID of the Instance.
Update an Instance › Request Body
nameName of the Instance.
boot_typetagsTags of the Instance.
dynamic_ip_requiredpublic_ipsA list of reserved IP IDs to attach to the Instance.
protectedTrue to activate server protection option.
placement_groupPlacement group ID if Instance must be part of a placement group.
private_nicsInstance private NICs.
commercial_typeSet the commercial_type for this Instance. Warning: This field has some restrictions:
- Cannot be changed if the Instance is not in
stoppedstate. - Cannot be changed if the Instance is in a placement group.
- Cannot be changed from/to a Windows offer to/from a Linux offer.
- Local storage requirements of the target commercial_types must be fulfilled (i.e. if an Instance has 80GB of local storage, it can be changed into a GP1-XS, which has a maximum of 150GB, but it cannot be changed into a DEV1-S, which has only 20GB).
admin_password_encryption_ssh_key_idUUID of the SSH RSA key that will be used to encrypt the initial admin password for OS requiring it. Mandatory for Windows OS. The public_key value of this key is used to encrypt the admin password. When set to an empty string, reset this value and admin_password_encrypted_value to an empty string so a new password may be generated.
routed_ip_enabledTrue to configure the instance so it uses the new routed IP mode (once this is set to True you cannot set it back to False).
enable_ipv6Update an Instance › Responses
List Instance actions
List all actions (e.g. power on, power off, reboot) that can currently be performed on an Instance.
path Parameters
zoneThe zone you want to target
server_idList Instance actions › Responses
actionsPerform action
Perform an action on an Instance. Available actions are:
poweron: Start a stopped Instance.poweroff: Fully stop the Instance and release the hypervisor slot.stop_in_place: Stop the Instance, but keep the slot on the hypervisor.reboot: Stop the instance and restart it.backup: Create an image with all the volumes of an Instance.terminate: Delete the Instance along with its attached local volumes.enable_routed_ip: Migrate the Instance to the new network stack.
The terminate action will result in the deletion of l_ssd and scratch volumes types, sbs_volume volumes will only be detached.
If you want to preserve your l_ssd volumes, you should stop your Instance, detach the volumes to be preserved, then delete your Instance.
The backup action can be done with:
- No
volumeskey in the body: an image is created with snapshots of all the server volumes, except for thescratchvolumes types. volumeskey in the body with a dictionary as value, in this dictionary volumes UUID as keys and empty dictionaries as values : an image is created with the snapshots of the volumes involumeskey.scratchvolumes types can't be shapshotted.
path Parameters
zoneThe zone you want to target
server_idUUID of the Instance.
Perform action › Request Body
actionAction to perform on the Instance.
nameName of the backup you want to create. Name of the backup you want to create. This field should only be specified when performing a backup action.
For each volume UUID, the snapshot parameters of the volume. For each volume UUID, the snapshot parameters of the volume. This field should only be specified when performing a backup action.
disable_ipv6Disable IPv6 on the Instance (true by default). Disable IPv6 on the Instance while performing migration to routed IPs. This field should only be specified when performing a enable_routed_ip action.
Perform action › Responses
Attach a filesystem volume to an Instance
Attach a volume to an Instance
path Parameters
zoneThe zone you want to target
server_idAttach a volume to an Instance › Request Body
volume_idvolume_typebootAttach a volume to an Instance › Responses
Get Instance compatible types
Get compatible commercial types that can be used to update the Instance. The compatibility of an Instance offer is based on:
- the CPU architecture
- the OS type
- the required l_ssd storage size
- the required scratch storage size If the specified Instance offer is flagged as end of service, the best compatible offer is the first returned.
path Parameters
zoneThe zone you want to target
server_idUUID of the Instance you want to get.
Get Instance compatible types › Responses
compatible_typesInstance compatible types.