Linode Instances

Linodes List

get

https://api.linode.com/v4/linode/instances

Returns a paginated list of Linodes you have permission to view.

Query Parameters

page

integer > = 1

Default: 1

The page of a collection to return.

page_size

integer [25 .. 500]

Default: 100

The number of items to return per page.

Request Samples

Shell
CLI

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/linode/instances

Response Samples

200
default

{
  "data": [
    {
      "id": "",
      "created": "2018-01-01T00:01:01",
      "status": "running",
      "label": "linode123",
      "type": "g6-standard-1",
      "updated": "2018-01-01T00:01:01",
      "group": "Linode-Group",
      "tags": [
        "example tag",
        "another example"
      ],
      "region": "us-east",
      "image": "linode/debian10",
      "hypervisor": "kvm",
      "ipv4": [],
      "ipv6": "c001:d00d::1337/128",
      "specs": {
        "disk": 81920,
        "memory": 4096,
        "vcpus": 2,
        "gpus": "",
        "transfer": 4000
      },
      "alerts": {
        "cpu": 180,
        "network_in": 10,
        "network_out": 10,
        "transfer_quota": 80,
        "io": 10000
      },
      "backups": {
        "enabled": true,
        "available": true,
        "schedule": "",
        "last_successful": "2018-01-01T00:01:01"
      },
      "watchdog_enabled": true,
      "host_uuid": "3a3ddd59d9a78bb8de041391075df44de62bfec8",
      "has_user_data": true
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

200: Returns an array of all Linodes on your Account.

data

array of objects

Filterable

integer

This Linode's ID which must be provided for all operations impacting this Linode.

created

string

When this Linode was created.

status

string

Enum: "running""offline""booting""rebooting""shutting_down""provisioning""deleting""migrating""rebuilding""cloning""restoring""stopped"

A brief description of this Linode's current state. This field may change without direct action from you. For example, when a Linode goes into maintenance mode its status will display "stopped".

label

Filterable

string^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$

The Linode's label is for display purposes only. If no label is provided for a Linode, a default will be assigned.

Linode labels have the following constraints:

Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.

type

string

This is the Linode Type that this Linode was deployed with. To change a Linode's Type, use POST /linode/instances/{linodeId}/resize.

updated

string

When this Linode was last updated.

group

Filterable

string

Deprecated

A deprecated property denoting a group label for this Linode.

tags

Filterable

array

An array of tags applied to this object. Tags are for organizational purposes only.

region

Filterable

string

This is the Region where the Linode was deployed. A Linode's region can only be changed by initiating a cross data center migration.

image

Filterable

Nullable

hypervisor

string

Enum: "kvm"

The virtualization software powering this Linode.

ipv4

Filterable

array

This Linode's IPv4 Addresses. Each Linode is assigned a single public IPv4 address upon creation, and may get a single private IPv4 address if needed. You may need to open a support ticket to get additional IPv4 addresses.

IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes. See the /networking endpoints for details.

ipv6

Nullable

string

This Linode's IPv6 SLAAC address. This address is specific to a Linode, and may not be shared. If the Linode has not been assigned an IPv6 address, the return value will be null.

specs

object

Information about the resources available to this Linode.

disk

integer

The amount of storage space, in MB, this Linode has access to. A typical Linode will divide this space between a primary disk with an image deployed to it, and a swap disk, usually 512 MB. This is the default configuration created when deploying a Linode with an image through POST /linode/instances. While this configuration is suitable for 99% of use cases, if you need finer control over your Linode's disks, see the /linode/instances/{linodeId}/disks endpoints.

memory

integer

The amount of RAM, in MB, this Linode has access to.

Typically, a Linode boots with all of its available RAM, but this can be configured in a Config profile. See the /linode/instances/{linodeId}/configs endpoints and the LinodeConfig object for more information.

vcpus

integer

The number of vcpus this Linode has access to.

gpus

integer

The number of gpus this Linode has access to.

transfer

integer

The amount of network transfer this Linode is allotted each month.

alerts

object

cpu

integer

The percentage of CPU usage required to trigger an alert. If the average CPU usage over two hours exceeds this value, we'll send you an alert. Your Linode's total CPU capacity is represented as 100%, multiplied by its number of cores.

For example, a two core Linode's CPU capacity is represented as 200%. If you want to be alerted at 90% of a two core Linode's CPU capacity, set the alert value to 180.

The default value is 90% multiplied by the number of cores.

If the value is set to 0 (zero), the alert is disabled.

network_in

integer

The amount of incoming traffic, in Mbit/s, required to trigger an alert. If the average incoming traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

network_out

integer

The amount of outbound traffic, in Mbit/s, required to trigger an alert. If the average outbound traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

transfer_quota

integer

The percentage of network transfer that may be used before an alert is triggered. When this value is exceeded, we'll alert you. If this is set to 0 (zero), the alert is disabled.

integer

The amount of disk IO operation per second required to trigger an alert. If the average disk IO over two hours exceeds this value, we'll send you an alert. If set to 0 (zero), this alert is disabled.

backups

object

Information about this Linode's backups status. For information about available backups, see /linode/instances/{linodeId}/backups.

enabled

boolean

If this Linode has the Backup service enabled. To enable backups, see POST /linode/instances/{linodeId}/backups/enable.

available

boolean

Whether Backups for this Linode are available for restoration.

Backups undergoing maintenance are not available for restoration.

schedule

object

day

Nullable

string

Enum: "Scheduling""Sunday""Monday""Tuesday""Wednesday""Thursday""Friday""Saturday"

The day of the week that your Linode's weekly Backup is taken. If not set manually, a day will be chosen for you. Backups are taken every day, but backups taken on this day are preferred when selecting backups to retain for a longer period.

If not set manually, then when backups are initially enabled, this may come back as Scheduling until the day is automatically selected.

window

Nullable

string

Enum: "Scheduling""W0""W2""W4""W6""W8""W10""W12""W14""W16""W18""W20""W22"

The window in which your backups will be taken, in UTC. A backups window is a two-hour span of time in which the backup may occur.

For example, W10 indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically.

If not set manually, when backups are initially enabled this may come back as Scheduling until the window is automatically selected.

last_successful

string

The last successful backup date. 'null' if there was no previous backup.

watchdog_enabled

boolean

The watchdog, named Lassie, is a Shutdown Watchdog that monitors your Linode and will reboot it if it powers off unexpectedly. It works by issuing a boot job when your Linode powers off without a shutdown job being responsible. To prevent a loop, Lassie will give up if there have been more than 5 boot jobs issued within 15 minutes.

host_uuid

string

The Linode's host machine, as a UUID.

has_user_data

boolean

Whether this compute instance was provisioned utilizing user_data provided via the Metadata service. See the Linode Create description for more information on Metadata.

page

integer

The current page.

pages

integer

The total number of pages.

results

integer

The total number of results.

default: Error

errors

array of objects

reason

string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field

string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Linode Create

post

https://api.linode.com/v4/linode/instances

Creates a Linode Instance on your Account. In order for this request to complete successfully, your User must have the add_linodes grant. Creating a new Linode will incur a charge on your Account.

Linodes can be created using one of the available Types. See Types List (GET /linode/types) to get more information about each Type's specs and cost.

Linodes can be created in any one of our available Regions, which are accessible from the Regions List (GET /regions) endpoint.

In an effort to fight spam, Linode restricts outbound connections on ports 25, 465, and 587 on all Linodes for new accounts created after November 5th, 2019. For more information, see our guide on Running a Mail Server.

Important: You must be an unrestricted User in order to add or modify tags on Linodes.

Linodes can be created in a number of ways:

Using a Linode Public Image distribution or a Private Image you created based on another Linode.
- Access the Images List (GET /images) endpoint with authentication to view all available Images.
- The Linode will be running after it completes provisioning.
- A default config with two Disks, one being a 512 swap disk, is created.
  - swap_size can be used to customize the swap disk size.
- Requires a root_pass be supplied to use for the root User's Account.
- It is recommended to supply SSH keys for the root User using the authorized_keys field.
- You may also supply a list of usernames via the authorized_users field.
  - These users must have an SSH Key associated with your Profile first. See SSH Key Add (POST /profile/sshkeys) for more information.
Using cloud-init with Metadata.
- Automate system configuration and software installation by providing a base-64 encoded cloud-config file.
- Requires a compatible Image. You can determine compatible Images by checking for cloud-init under capabilities when using Images List (GET /images).
- Requires a compatible Region. You can determine compatible Regions by checking for Metadata under capabilities when using Regions List (GET /regions).
Using a StackScript.
- See StackScripts List (GET /linode/stackscripts) for a list of available StackScripts.
- The Linode will be running after it completes provisioning.
- Requires a compatible Image to be supplied.
  - See StackScript View (GET /linode/stackscript/{stackscriptId}) for compatible Images.
- Requires a root_pass be supplied to use for the root User's Account.
- It is recommended to supply SSH keys for the root User using the authorized_keys field.
- You may also supply a list of usernames via the authorized_users field.
  - These users must have an SSH Key associated with your Profile first. See SSH Key Add (POST /profile/sshkeys) for more information.
Using one of your other Linode's backups.
- You must create a Linode large enough to accommodate the Backup's size.
- The Disks and Config will match that of the Linode that was backed up.
- The root_pass will match that of the Linode that was backed up.
Attached to a private VLAN.
- Review the interfaces property of the Request Body Schema for details.
- For more information, see our guide on Getting Started with VLANs.
Create an empty Linode.
- The Linode will remain offline and must be manually started.
  - See Linode Boot (POST /linode/instances/{linodeId}/boot).
- Disks and Configs must be created manually.
- This is only recommended for advanced use cases.

Request Body Schema

authorized_keys

array

A list of public SSH keys that will be automatically appended to the root user's ~/.ssh/authorized_keys file when deploying from an Image.

authorized_users

array

A list of usernames. If the usernames have associated SSH keys, the keys will be appended to the root users ~/.ssh/authorized_keys file automatically when deploying from an Image.

booted

boolean

This field defaults to true if the Linode is created with an Image or from a Backup. If it is deployed from an Image or a Backup and you wish it to remain offline after deployment, set this to false.

image

string

An Image ID to deploy the Linode Disk from.

Access the Images List (GET /images) endpoint with authentication to view all available Images. Official Linode Images start with linode/, while your Account's Images start with private/. Creating a disk from a Private Image requires read_only or read_write permissions for that Image. Access the User's Grant Update (PUT /account/users/{username}/grants) endpoint to adjust permissions for an Account Image.

metadata

object

An object containing user-defined data relevant to the creation of Linodes.

user_data

string

Base64-encoded cloud-config data.

Cannot be modified after provisioning. To update, use either the Linode Clone or Linode Rebuild commands.

Must not be included when cloning to an existing Linode.

Unencoded data must not exceed 65535 bytes, or about 16kb encoded.

root_pass

string <password>[7 .. 128] characters

This sets the root user's password on a newly-created Linode Disk when deploying from an Image.

Required when creating a Linode Disk from an Image, including when using a StackScript.
Must meet a password strength score requirement that is calculated internally by the API. If the strength requirement is not met, you will receive a Password does not meet strength requirement error.

stackscript_data

object

This field is required only if the StackScript being deployed requires input data from the User for successful completion. See User Defined Fields (UDFs) for more details.

This field is required to be valid JSON.

Total length cannot exceed 65,535 characters.

stackscript_id

integer

A StackScript ID that will cause the referenced StackScript to be run during deployment of this Linode. A compatible image is required to use a StackScript. To get a list of available StackScript and their permitted Images see /stackscripts. This field cannot be used when deploying from a Backup or a Private Image.

region

Required

string

The Region where the Linode will be located.

type

Required

string

The Linode Type of the Linode you are creating.

backup_id

integer

A Backup ID from another Linode's available backups. Your User must have read_write access to that Linode, the Backup must have a status of successful, and the Linode must be deployed to the same region as the Backup. See GET /linode/instances/{linodeId}/backups for a Linode's available backups.

This field and the image field are mutually exclusive.

backups_enabled

boolean

If this field is set to true, the created Linode will automatically be enrolled in the Linode Backup service. This will incur an additional charge. The cost for the Backup service is dependent on the Type of Linode deployed.

This option is always treated as true if the account-wide backups_enabled setting is true. See account settings for more information.

Backup pricing is included in the response from /linodes/types

group

Filterable

string

A deprecated property denoting a group label for this Linode.

interfaces

array

An array of Network Interfaces to add to this Linode's Configuration Profile.

Up to three interface objects can be entered in this array. The position in the array determines the interface to which the settings apply:

First 0: eth0
Second 1: eth1
Third 2: eth2

When updating a Linode's interfaces, each interface must be redefined. An empty interfaces array results in a default public interface configuration only.

If no public interface is configured, public IP addresses are still assigned to the Linode but will not be usable without manual configuration.

Note: Changes to Linode interface configurations can be enabled by rebooting the Linode.

Note: Only Next Generation Network (NGN) data centers support VLANs. Use the Regions (/regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated because of an incompatibility, you will be prompted to select a different data center or contact support.

Note: See the VLANs Overview guide to view additional specifications and limitations.

label

Filterable

string [3 .. 64] characters ^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$

The Linode's label is for display purposes only. If no label is provided for a Linode, a default will be assigned.

Linode labels have the following constraints:

Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.

private_ip

boolean

If true, the created Linode will have private networking enabled and assigned a private IPv4 address.

swap_size

integer

When deploying from an Image, this field is optional, otherwise it is ignored. This is used to set the swap disk size for the newly-created Linode.

tags

Filterable

array

An array of tags applied to this object. Tags are for organizational purposes only.

Request Samples

Shell
CLI

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "backup_id": 1234,
      "backups_enabled": true,
      "swap_size": 512,
      "image": "linode/ubuntu22.04",
      "root_pass": "aComplexP@ssword",
      "stackscript_id": 10079,
      "stackscript_data": {
        "gh_username": "linode"
      },
      "interfaces": [
        {
          "purpose": "public",
          "label": "",
          "ipam_address": ""
        },
        {
          "purpose": "vlan",
          "label": "vlan-1",
          "ipam_address": "10.0.0.1/24"
        }
      ],
      "authorized_keys": [
        "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
      ],
      "authorized_users": [
        "myUser",
        "secondaryUser"
      ],
      "booted": true,
      "label": "linode123",
      "type": "g6-standard-2",
      "region": "us-east",
      "group": "Linode-Group",
      "metadata": {
        "user_data": "I2Nsb3VkLWNvbmZpZw=="
      }
    }' \
    https://api.linode.com/v4/linode/instances

Response Samples

200
default

{
  "status": "running",
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "id": 1234,
  "label": "linode123",
  "type": "g6-standard-1",
  "region": "us-east",
  "group": "Linode-Group",
  "tags": [],
  "image": "linode/debian10",
  "hypervisor": "kvm",
  "ipv4": [],
  "ipv6": "c001:d00d::1337/128",
  "specs": {
    "disk": 81920,
    "memory": 4096,
    "vcpus": 2,
    "gpus": 0,
    "transfer": 4000
  },
  "alerts": {
    "cpu": 180,
    "network_in": 10,
    "network_out": 10,
    "transfer_quota": 80,
    "io": 10000
  },
  "backups": {
    "enabled": true,
    "available": true,
    "schedule": {
      "day": "Saturday",
      "window": "W22"
    },
    "last_successful": "2018-01-01T00:01:01"
  },
  "watchdog_enabled": true,
  "host_uuid": "3a3ddd59d9a78bb8de041391075df44de62bfec8",
  "has_user_data": true
}

Responses

200: A new Linode is being created.

status

string

Enum: "running""offline""booting""rebooting""shutting_down""provisioning""deleting""migrating""rebuilding""cloning""restoring""stopped"

A brief description of this Linode's current state. This field may change without direct action from you. For example, when a Linode goes into maintenance mode its status will display "stopped".

created

string <date-time>

When this Linode was created.

updated

string <date-time>

When this Linode was last updated.

Filterable

integer

This Linode's ID which must be provided for all operations impacting this Linode.

label

Filterable

string [3 .. 64] characters ^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$

The Linode's label is for display purposes only. If no label is provided for a Linode, a default will be assigned.

Linode labels have the following constraints:

Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.

type

string

This is the Linode Type that this Linode was deployed with. To change a Linode's Type, use POST /linode/instances/{linodeId}/resize.

region

Filterable

string

This is the Region where the Linode was deployed. A Linode's region can only be changed by initiating a cross data center migration.

group

Filterable

string

Deprecated

A deprecated property denoting a group label for this Linode.

tags

Filterable

array of objects

An array of tags applied to this object. Tags are for organizational purposes only.

image

Filterable

Nullable

hypervisor

string

Enum: "kvm"

The virtualization software powering this Linode.

ipv4

Filterable

array of objects <ipv4>

IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes. See the /networking endpoints for details.

ipv6

Nullable

string <ipv6/128>

This Linode's IPv6 SLAAC address. This address is specific to a Linode, and may not be shared. If the Linode has not been assigned an IPv6 address, the return value will be null.

specs

object

Information about the resources available to this Linode.

disk

integer

memory

integer

The amount of RAM, in MB, this Linode has access to.

vcpus

integer

The number of vcpus this Linode has access to.

gpus

integer

The number of gpus this Linode has access to.

transfer

integer

The amount of network transfer this Linode is allotted each month.

alerts

object

cpu

integer

For example, a two core Linode's CPU capacity is represented as 200%. If you want to be alerted at 90% of a two core Linode's CPU capacity, set the alert value to 180.

The default value is 90% multiplied by the number of cores.

If the value is set to 0 (zero), the alert is disabled.

network_in

integer

network_out

integer

transfer_quota

integer

The percentage of network transfer that may be used before an alert is triggered. When this value is exceeded, we'll alert you. If this is set to 0 (zero), the alert is disabled.

integer

backups

object

Information about this Linode's backups status. For information about available backups, see /linode/instances/{linodeId}/backups.

enabled

boolean

If this Linode has the Backup service enabled. To enable backups, see POST /linode/instances/{linodeId}/backups/enable.

available

boolean

Whether Backups for this Linode are available for restoration.

Backups undergoing maintenance are not available for restoration.

schedule

object

day

Nullable

string

Enum: "Scheduling""Sunday""Monday""Tuesday""Wednesday""Thursday""Friday""Saturday"

If not set manually, then when backups are initially enabled, this may come back as Scheduling until the day is automatically selected.

window

Nullable

string

Enum: "Scheduling""W0""W2""W4""W6""W8""W10""W12""W14""W16""W18""W20""W22"

The window in which your backups will be taken, in UTC. A backups window is a two-hour span of time in which the backup may occur.

For example, W10 indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically.

If not set manually, when backups are initially enabled this may come back as Scheduling until the window is automatically selected.

last_successful

string

The last successful backup date. 'null' if there was no previous backup.

watchdog_enabled

boolean

host_uuid

string <uuid>

The Linode's host machine, as a UUID.

has_user_data

boolean

Whether this compute instance was provisioned utilizing user_data provided via the Metadata service. See the Linode Create description for more information on Metadata.

default: Error

errors

array of objects

reason

string

field

string

Compute

Storage

Databases

Networking

Developer Tools

Delivery

Security

Services

Industries

Pricing

Community

Engage With Us

Linode Instances

Linodes List

Query Parameters

Request Samples

Response Samples

Responses

Linode Create

Request Body Schema

Request Samples

Response Samples

Responses