List Neighbors

List Neighbors for a Droplet

get/v2/droplets/{droplet_id}/neighbors

To retrieve a list of any "neighbors" (i.e. Droplets that are co-located on the same physical hardware) for a specific Droplet, send a GET request to /v2/droplets/$DROPLET_ID/neighbors.

The results will be returned as a JSON object with a key of droplets. This will be set to an array containing objects representing any other Droplets that share the same physical hardware. An empty array indicates that the Droplet is not co-located any other Droplets associated with your account.

Path ParametersExpand Collapse

droplet_id: number

minimum1

ReturnsExpand Collapse

droplets: optional array of Droplet { id, backup_ids, created_at, 20 more }

id: number

A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.

backup_ids: array of number

An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.

created_at: string

A time value given in ISO8601 combined date and time format that represents when the Droplet was created.

formatdate-time

disk: number

The size of the Droplet's disk in gigabytes.

features: array of string

An array of features enabled on this Droplet.

image: Image { id, created_at, description, 11 more }

The Droplet's image.
Requires image:read scope.

id: optional number

A unique number that can be used to identify and reference a specific image.

created_at: optional string

A time value given in ISO8601 combined date and time format that represents when the image was created.

formatdate-time

description: optional string

An optional free-form text field to describe an image.

distribution: optional "Arch Linux" or "CentOS" or "CoreOS" or 10 more

The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place.

Accepts one of the following:

"Arch Linux"

"CentOS"

"CoreOS"

"Debian"

"Fedora"

"Fedora Atomic"

"FreeBSD"

"Gentoo"

"openSUSE"

"RancherOS"

"Rocky Linux"

"Ubuntu"

"Unknown"

error_message: optional string

A string containing information about errors that may occur when importing a custom image.

min_disk_size: optional number

The minimum disk size in GB required for a Droplet to use this image.

minimum0

The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.

public: optional boolean

This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account.

regions: optional array of "ams1" or "ams2" or "ams3" or 12 more

This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.

Accepts one of the following:

"ams1"

"ams2"

"ams3"

"blr1"

"fra1"

"lon1"

"nyc1"

"nyc2"

"nyc3"

"sfo1"

"sfo2"

"sfo3"

"sgp1"

"tor1"

"syd1"

size_gigabytes: optional number

The size of the image in gigabytes.

formatfloat

slug: optional string

A uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id.

status: optional "NEW" or "available" or "pending" or 2 more

A status string indicating the state of a custom image. This may be NEW, available, pending, deleted, or retired.

Accepts one of the following:

"NEW"

"available"

"pending"

"deleted"

"retired"

tags: optional array of string

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

type: optional "base" or "snapshot" or "backup" or 2 more

Describes the kind of image. It may be one of base, snapshot, backup, custom, or admin. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes).

Accepts one of the following:

"base"

"snapshot"

"backup"

"custom"

"admin"

locked: boolean

A boolean value indicating whether the Droplet has been locked, preventing actions by users.

memory: number

Memory of the Droplet in megabytes.

multipleOf8

The human-readable name set for the Droplet instance.

networks: object { v4, v6 }

The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

v4: optional array of NetworkV4 { gateway, ip_address, netmask, type }

gateway: optional string

The gateway of the specified IPv4 network interface.

For private interfaces, a gateway is not provided. This is denoted by returning nil as its value.

ip_address: optional string

The IP address of the IPv4 network interface.

formatipv4

netmask: optional string

The netmask of the IPv4 network interface.

formatipv4

type: optional "public" or "private"

The type of the IPv4 network interface.

Accepts one of the following:

"public"

"private"

v6: optional array of NetworkV6 { gateway, ip_address, netmask, type }

gateway: optional string

The gateway of the specified IPv6 network interface.

formatipv6

ip_address: optional string

The IP address of the IPv6 network interface.

formatipv6

netmask: optional number

The netmask of the IPv6 network interface.

type: optional "public"

The type of the IPv6 network interface.

Note: IPv6 private networking is not currently supported.

Accepts one of the following:

"public"

next_backup_window: DropletNextBackupWindow { end, start }

The details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.

end: optional string

A time value given in ISO8601 combined date and time format specifying the end of the Droplet's backup window.

formatdate-time

start: optional string

A time value given in ISO8601 combined date and time format specifying the start of the Droplet's backup window.

formatdate-time

region: Region { available, features, name, 2 more }

available: boolean

This is a boolean value that represents whether new Droplets can be created in this region.

features: array of string

This attribute is set to an array which contains features available in this region

The display name of the region. This will be a full name that is used in the control panel and other interfaces.

sizes: array of string

This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.

slug: string

A human-readable string that is used as a unique identifier for each region.

size: Size { available, description, disk, 9 more }

available: boolean

This is a boolean value that represents whether new Droplets can be created with this size.

description: string

A string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.

disk: number

The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.

memory: number

The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.

multipleOf8

minimum8

price_hourly: number

This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.

formatfloat

price_monthly: number

This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.

formatfloat

regions: array of string

An array containing the region slugs where this size is available for Droplet creates.

slug: string

A human-readable string that is used to uniquely identify each size.

transfer: number

The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.

formatfloat

vcpus: number

The number of CPUs allocated to Droplets of this size.

disk_info: optional array of DiskInfo { size, type }

An array of objects containing information about the disks available to Droplets created with this size.

size: optional object { amount, unit }

amount: optional number

The amount of space allocated to the disk.

unit: optional string

The unit of measure for the disk size.

type: optional "local" or "scratch"

The type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.

Accepts one of the following:

"local"

"scratch"

gpu_info: optional GPUInfo { count, model, vram }

An object containing information about the GPU capabilities of Droplets created with this size.

The number of GPUs allocated to the Droplet.

model: optional string

The model of the GPU.

vram: optional object { amount, unit }

amount: optional number

The amount of VRAM allocated to the GPU.

unit: optional string

The unit of measure for the VRAM.

size_slug: string

The unique slug identifier for the size of this Droplet.

snapshot_ids: array of number

An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.

status: "new" or "active" or "off" or "archive"

A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".

Accepts one of the following:

"new"

"active"

"off"

"archive"

tags: array of string

An array of Tags the Droplet has been tagged with.
Requires tag:read scope.

vcpus: number

The number of virtual CPUs.

volume_ids: array of string

A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.

disk_info: optional array of DiskInfo { size, type }

An array of objects containing information about the disks available to the Droplet.

size: optional object { amount, unit }

amount: optional number

The amount of space allocated to the disk.

unit: optional string

The unit of measure for the disk size.

type: optional "local" or "scratch"

The type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.

Accepts one of the following:

"local"

"scratch"

gpu_info: optional GPUInfo { count, model, vram }

An object containing information about the GPU capabilities of Droplets created with this size.

The number of GPUs allocated to the Droplet.

model: optional string

The model of the GPU.

vram: optional object { amount, unit }

amount: optional number

The amount of VRAM allocated to the GPU.

unit: optional string

The unit of measure for the VRAM.

Deprecatedkernel: optional Kernel { id, name, version }

Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null.

The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.

id: optional number

A unique number used to identify and reference a specific kernel.

The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.

version: optional string

A standard kernel version string representing the version, patch, and release information.

vpc_uuid: optional string

A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.

List Neighbors for a Droplet

curl https://api.digitalocean.com/v2/droplets/$DROPLET_ID/neighbors \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN"

{
  "droplets": [
    {
      "id": 3164444,
      "backup_ids": [
        53893572
      ],
      "created_at": "2020-07-21T18:37:44Z",
      "disk": 25,
      "features": [
        "backups",
        "private_networking",
        "ipv6"
      ],
      "image": {
        "id": 7555620,
        "created_at": "2020-05-04T22:23:02Z",
        "description": " ",
        "distribution": "Ubuntu",
        "error_message": " ",
        "min_disk_size": 20,
        "name": "Nifty New Snapshot",
        "public": true,
        "regions": [
          "nyc1",
          "nyc2"
        ],
        "size_gigabytes": 2.34,
        "slug": "nifty1",
        "status": "NEW",
        "tags": [
          "base-image",
          "prod"
        ],
        "type": "snapshot"
      },
      "locked": false,
      "memory": 1024,
      "name": "example.com",
      "networks": {
        "v4": [
          {
            "gateway": "104.236.0.1",
            "ip_address": "104.236.32.182",
            "netmask": "255.255.192.0",
            "type": "public"
          }
        ],
        "v6": [
          {
            "gateway": "2604:a880:0:1010::1",
            "ip_address": "2604:a880:0:1010::18a:a001",
            "netmask": 64,
            "type": "public"
          }
        ]
      },
      "next_backup_window": {
        "end": "2019-12-04T23:00:00Z",
        "start": "2019-12-04T00:00:00Z"
      },
      "region": {
        "available": true,
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "name": "New York 3",
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192g"
        ],
        "slug": "nyc3"
      },
      "size": {
        "available": true,
        "description": "Basic",
        "disk": 25,
        "memory": 1024,
        "price_hourly": 0.00743999984115362,
        "price_monthly": 5,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "slug": "s-1vcpu-1gb",
        "transfer": 1,
        "vcpus": 1,
        "disk_info": [
          {
            "size": {
              "amount": 25,
              "unit": "gib"
            },
            "type": "local"
          }
        ],
        "gpu_info": {
          "count": 1,
          "model": "nvidia_h100",
          "vram": {
            "amount": 25,
            "unit": "gib"
          }
        }
      },
      "size_slug": "s-1vcpu-1gb",
      "snapshot_ids": [
        67512819
      ],
      "status": "active",
      "tags": [
        "web",
        "env:prod"
      ],
      "vcpus": 1,
      "volume_ids": [
        "506f78a4-e098-11e5-ad9f-000f53306ae1"
      ],
      "disk_info": [
        {
          "size": {
            "amount": 25,
            "unit": "gib"
          },
          "type": "local"
        }
      ],
      "gpu_info": {
        "count": 1,
        "model": "nvidia_h100",
        "vram": {
          "amount": 25,
          "unit": "gib"
        }
      },
      "kernel": {
        "id": 7515,
        "name": "DigitalOcean GrubLoader v0.2 (20160714)",
        "version": "2016.07.13-DigitalOcean_loader_Ubuntu"
      },
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
    }
  ]
}

Returns Examples

{
  "droplets": [
    {
      "id": 3164444,
      "backup_ids": [
        53893572
      ],
      "created_at": "2020-07-21T18:37:44Z",
      "disk": 25,
      "features": [
        "backups",
        "private_networking",
        "ipv6"
      ],
      "image": {
        "id": 7555620,
        "created_at": "2020-05-04T22:23:02Z",
        "description": " ",
        "distribution": "Ubuntu",
        "error_message": " ",
        "min_disk_size": 20,
        "name": "Nifty New Snapshot",
        "public": true,
        "regions": [
          "nyc1",
          "nyc2"
        ],
        "size_gigabytes": 2.34,
        "slug": "nifty1",
        "status": "NEW",
        "tags": [
          "base-image",
          "prod"
        ],
        "type": "snapshot"
      },
      "locked": false,
      "memory": 1024,
      "name": "example.com",
      "networks": {
        "v4": [
          {
            "gateway": "104.236.0.1",
            "ip_address": "104.236.32.182",
            "netmask": "255.255.192.0",
            "type": "public"
          }
        ],
        "v6": [
          {
            "gateway": "2604:a880:0:1010::1",
            "ip_address": "2604:a880:0:1010::18a:a001",
            "netmask": 64,
            "type": "public"
          }
        ]
      },
      "next_backup_window": {
        "end": "2019-12-04T23:00:00Z",
        "start": "2019-12-04T00:00:00Z"
      },
      "region": {
        "available": true,
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "name": "New York 3",
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192g"
        ],
        "slug": "nyc3"
      },
      "size": {
        "available": true,
        "description": "Basic",
        "disk": 25,
        "memory": 1024,
        "price_hourly": 0.00743999984115362,
        "price_monthly": 5,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "slug": "s-1vcpu-1gb",
        "transfer": 1,
        "vcpus": 1,
        "disk_info": [
          {
            "size": {
              "amount": 25,
              "unit": "gib"
            },
            "type": "local"
          }
        ],
        "gpu_info": {
          "count": 1,
          "model": "nvidia_h100",
          "vram": {
            "amount": 25,
            "unit": "gib"
          }
        }
      },
      "size_slug": "s-1vcpu-1gb",
      "snapshot_ids": [
        67512819
      ],
      "status": "active",
      "tags": [
        "web",
        "env:prod"
      ],
      "vcpus": 1,
      "volume_ids": [
        "506f78a4-e098-11e5-ad9f-000f53306ae1"
      ],
      "disk_info": [
        {
          "size": {
            "amount": 25,
            "unit": "gib"
          },
          "type": "local"
        }
      ],
      "gpu_info": {
        "count": 1,
        "model": "nvidia_h100",
        "vram": {
          "amount": 25,
          "unit": "gib"
        }
      },
      "kernel": {
        "id": 7515,
        "name": "DigitalOcean GrubLoader v0.2 (20160714)",
        "version": "2016.07.13-DigitalOcean_loader_Ubuntu"
      },
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
    }
  ]
}