pydo.droplets.list()

Generated on 3 Aug 2026 from pydo version v0.40.0

Copy page as Markdown View page as Markdown

Usage 

client.droplets.list(
    per_page=20,
    page=1,
    tag_name=None,
    name=None,
    type=None,
)
Returns JSONRaises HttpResponseError

Description

To list all Droplets in your account, send a GET request to /v2/droplets.

The response body will be a JSON object with a key of droplets. This will be set to an array containing objects each representing a Droplet. These will contain the standard Droplet attributes.

Filtering Results by Tag

It’s possible to request filtered results by including certain query parameters. To only list Droplets assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your GET request. For example, /v2/droplets?tag_name=$TAG_NAME.

GPU Droplets

By default, only non-GPU Droplets are returned. To list only GPU Droplets, set the type query parameter to gpus. For example, /v2/droplets?type=gpus.

Parameters

per_page integer optional

Number of items returned per page

Min: 1

Max: 200

Default: 20

page integer optional

Which 'page' of paginated results to return.

Min: 1

Default: 1

tag_name string optional

Used to filter Droplets by a specific tag. Can not be combined with name or type.
Requires tag:read scope.

name string optional

Used to filter list response by Droplet name returning only exact matches. It is case-insensitive and can not be combined with tag_name.

type string optional

When type is set to gpus, only GPU Droplets will be returned. By default, only non-GPU Droplets are returned. Can not be combined with tag_name.

One of: droplets, gpus

Request Sample

Show Request Sample
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.droplets.list()

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.droplets.list()
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.droplets.list(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

Show Response Example
{
  "droplets": [
    {
      "id": 3164444,
      "name": "example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:37:44Z",
      "features": [
        "backups",
        "private_networking",
        "ipv6"
      ],
      "backup_ids": [
        53893572
      ],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [
        67512819
      ],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.124",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "192.241.165.154",
            "netmask": "255.255.255.0",
            "gateway": "192.241.165.1",
            "type": "public"
          }
        ],
        "v6": [
          {
            "ip_address": "2604:a880:0:1010::18a:a001",
            "netmask": 64,
            "gateway": "2604:a880:0:1010::1",
            "type": "public"
          }
        ]
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "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"
        ]
      },
      "tags": [
        "web",
        "env:prod"
      ],
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
    },
    {
      "id": 3164459,
      "name": "assets.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:42:27Z",
      "features": [
        "private_networking"
      ],
      "backup_ids": [],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [
        "506f78a4-e098-11e5-ad9f-000f53306ae1"
      ],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.138",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "162.243.0.4",
            "netmask": "255.255.255.0",
            "gateway": "162.243.0.1",
            "type": "public"
          }
        ],
        "v6": []
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "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"
        ]
      },
      "tags": [
        "storage",
        "env:prod"
      ],
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
    },
    {
      "id": 3164412,
      "name": "stage.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:32:55Z",
      "features": [
        "private_networking"
      ],
      "backup_ids": [],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [
        "7724db7c-e098-11e5-b522-000f53304e51"
      ],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.125",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "192.241.247.248",
            "netmask": "255.255.255.0",
            "gateway": "192.241.247.1",
            "type": "public"
          }
        ],
        "v6": []
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "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"
        ]
      },
      "tags": [
        "env:stage"
      ],
      "vpc_uuid": "5a4981aa-9653-4bd1-bef5-d6bff52042e4"
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 3
  }
}

More Information

See /v2/droplets in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.