Linode Instances

Linode View

get
https://api.linode.com/v4/linode/instances/{linodeId}

Get a specific Linode by ID.

Path Parameters

linodeId
Required
integer

ID of the Linode to look up

Request Samples

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

Response Samples

{
  "status": "running",
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "id": 1234,
  "label": "linode123",
  "type": "g6-standard-1",
  "image": "linode/debian10",
  "region": "us-east",
  "group": "Linode-Group",
  "tags": [],
  "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: Returns a single Linode object.

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.

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

image
Filterable
Nullable
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.

hypervisor
string
Enum: "kvm"

The virtualization software powering this Linode.

ipv4
Filterable
array of objects <ipv4>

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

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.

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.

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

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 Update

put
https://api.linode.com/v4/linode/instances/{linodeId}

Updates a Linode that you have permission to read_write.

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

Path Parameters

linodeId
Required
integer

ID of the Linode to look up

Request Body Schema

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.

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.

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.

group
Filterable
string
Deprecated

A deprecated property denoting a group label for 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.
tags
Filterable
array

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

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.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X PUT -d '{
      "label": "linode123",
      "group": "Linode-Group",
      "alerts": {
        "cpu": 180,
        "network_in": 10,
        "network_out": 10,
        "transfer_quota": 80,
        "io": 10000
      },
      "backups": {
        "schedule": {
          "day": "Saturday",
          "window": "W22"
        }
      }
    }' \
    https://api.linode.com/v4/linode/instances/123

Response Samples

{
  "id": 1234,
  "label": "linode123",
  "status": "running",
  "image": "linode/debian10",
  "type": "g6-standard-1",
  "region": "us-east",
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "group": "Linode-Group",
  "tags": [],
  "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: The updated Linode.

id
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.
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".

image
Filterable
Nullable
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.

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.

updated
string <date-time>

When this Linode was last updated.

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.

hypervisor
string
Enum: "kvm"

The virtualization software powering this Linode.

ipv4
Filterable
array of objects <ipv4>

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

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.

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.

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

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 Delete

delete
https://api.linode.com/v4/linode/instances/{linodeId}

Deletes a Linode you have permission to read_write.

Deleting a Linode is a destructive action and cannot be undone.

Additionally, deleting a Linode:

  • Gives up any IP addresses the Linode was assigned.
  • Deletes all Disks, Backups, Configs, etc.
  • Detaches any Volumes associated with the Linode.
  • Stops billing for the Linode and its associated services. You will be billed for time used within the billing period the Linode was active.

Linodes that are in the process of cloning or backup restoration cannot be deleted.

Path Parameters

linodeId
Required
integer

ID of the Linode to look up

Request Samples

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

Response Samples

{}

Responses

200: Delete successful

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.