Linode Instances

List Linodes

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

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

Authorizations

Personal Access Token
OAuth: ( linodes:read_only)

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 100]
Default: 100

The number of items to return per page.

Request Samples

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

Response Samples

{
  "data": [
    {
      "id": "",
      "created": "2018-01-01T00:01:01",
      "status": "running",
      "label": "",
      "type": "",
      "group": "Linode-Group",
      "tags": [
        "example tag",
        "another example"
      ],
      "region": "",
      "image": "",
      "hypervisor": "kvm",
      "updated": "2018-01-01T00:01:01",
      "ipv4": [],
      "ipv6": "c001:d00d::1234",
      "specs": {
        "disk": 81920,
        "memory": 4096,
        "vcpus": 2,
        "transfer": 4000
      },
      "alerts": {
        "cpu": 180,
        "network_in": 10,
        "network_out": 10,
        "transfer_quota": 80,
        "io": 10000
      },
      "backups": {
        "enabled": true,
        "schedule": ""
      },
      "watchdog_enabled": true
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

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

data
array of objects
id
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"

A brief description of this Linode's current state. This field may change without direct action from you. For instance, the status will change to "running" when the boot process completes.

label
Filterable

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 start with an alpha character.
  • May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
  • Cannot have two dashes (--), underscores (__) or periods (..) in a row.
type

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

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

This is the location where the Linode was deployed. This cannot be changed without opening a support ticket.

image
Filterable
Nullable
hypervisor
string
Enum: "kvm"

The virtualization software powering this Linode.

updated
string

When this Linode was last updated.

ipv4
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
string

This Linode's IPv6 SLAAC addresses. 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 will choose to boot 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. Typically a Linode will choose to boot with all of its available vcpus, but this can be configured in a Config Profile, see the /linode/instances/{linodeId}/configs endpoints and the LinodeConfig object for more information.

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.

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.

io
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.

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.

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.

page
integer
pages
integer
results
integer

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.

Create Linode

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 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 for a list of available Regions you can deploy your Linode in.

Linodes can be created in a number of ways:

  • Using a Linode Linux Distribution image or an Image you created based on another Linode.

    • 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 /profile/sshkeys for more information.
  • Using a StackScript.

    • See /linode/stackscripts for a list of available StackScripts.
    • The Linode will be running after it completes provisioning.
    • Requires a compatible Image to be supplied.
    • 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 /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.
  • Create an empty Linode.

    • The Linode will remain offline and must be manually started.
    • Disks and Configs must be created manually.
    • This is only recommended for advanced use cases.

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

Authorizations

Personal Access Token
OAuth: ( linodes:read_write)

Request Body Schema

region
Required
string

The Region where the Linode will be located.

type
Required
string

The Linode Type of the Linode you are creating.

authorized_keys
array

A list of SSH public keys to deploy for the root user on the newly-created Linode. Only accepted if image is provided.

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.

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 /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

booted
boolean

Whether to boot this Linode after the deploy is complete. Defaults to true if image is provided. Not accepted if not deploying from an Image.

group
Filterable
string
Deprecated

A deprecated property denoting a group label for this Linode.

image
string

An Image ID to deploy the Disk from. Official Linode Images start with linode/, while your Images start with private/. See /images for more information on the Images available for you to use.

label
Filterable

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 start with an alpha 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.

root_pass
string <password>[6 .. 128] characters ^(((?=.*[a-z])(?=.*[A-Z]))|((?=.*[a-z])(?=.*[0-9]))|((?=.*[A-Z])(?=.*[0-9]))|((?=.*[a-z])(?=.*[!"#$%&'()*+,-.\/:;<=>?@\[\]^_`{|}~\\]))|((?=.*[A-Z])(?=.*[!"#$%&'()*+,-.\/:;<=>?@\[\]^_`{|}~\\]))|((?=.*[0-9])(?=.*[!"#$%&'()*+,-.\/:;<=>?@\[\]^_`{|}~\\])))

This will set the root user's password on the newly-created Linode. The root password must conform to the following constraints:

  • May only use alphanumerics, punctuation, spaces, and tabs.
  • Must contain at least two of the following characters classes:
    • Upper-case letters
    • Lower-case letters
    • Digits
    • Punctuation
stackscript_data
object

An object containing responses to any User Defined Fields present in the StackScript being deployed to this Linode. Only accepted if stackscript_id is given. The required values depend on the StackScript being deployed.

stackscript_id
integer

The StackScript to deploy to the newly-created Linode. If provided, "image" must also be provided, and must be an Image that is compatible with this StackScript.

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

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "backup_id": 1234,
      "backups_enabled": true,
      "swap_size": 512,
      "image": "linode/debian9",
      "root_pass": "aComplexP@ssword",
      "stackscript_id": 10079,
      "stackscript_data": {
        "gh_username": "linode"
      },
      "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"
    }' \
    https://api.linode.com/v4/linode/instances

Response Samples

{
  "id": 1234,
  "label": "",
  "status": "running",
  "type": "",
  "group": "Linode-Group",
  "tags": [],
  "created": "2018-01-01T00:01:01",
  "region": "",
  "image": "",
  "hypervisor": "kvm",
  "updated": "2018-01-01T00:01:01",
  "ipv4": [],
  "ipv6": "c001:d00d::1234",
  "specs": [
    {
      "disk": 81920,
      "memory": 4096,
      "vcpus": 2,
      "transfer": 4000
    }
  ],
  "alerts": [
    {
      "cpu": 180,
      "network_in": 10,
      "network_out": 10,
      "transfer_quota": 80,
      "io": 10000
    }
  ],
  "backups": [
    {
      "enabled": true,
      "schedule": ""
    }
  ],
  "watchdog_enabled": true
}

Responses

200: A new Linode is being created.

id
Filterable
integer

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

label
Filterable

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 start with an alpha character.
  • May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
  • Cannot have two dashes (--), underscores (__) or periods (..) in a row.
status
string
Enum: "running""offline""booting""rebooting""shutting_down""provisioning""deleting""migrating""rebuilding""cloning""restoring"

A brief description of this Linode's current state. This field may change without direct action from you. For instance, the status will change to "running" when the boot process completes.

type

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

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.

created
string <date-time>

When this Linode was created.

region
Filterable

This is the location where the Linode was deployed. This cannot be changed without opening a support ticket.

image
Filterable
Nullable
hypervisor
string
Enum: "kvm"

The virtualization software powering this Linode.

updated
string <date-time>

When this Linode was last updated.

ipv4
array of objects

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
string

This Linode's IPv6 SLAAC addresses. 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 will choose to boot 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. Typically a Linode will choose to boot with all of its available vcpus, but this can be configured in a Config Profile, see the /linode/instances/{linodeId}/configs endpoints and the LinodeConfig object for more information.

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.

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.

io
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.

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.

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.

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.