pydo.volumes.list()

Generated on 25 November 2024 from pydo version v0.6.0

Description

To list all of the block storage volumes available on your account, send a GET request to /v2/volumes.

Filtering Results

By Region

The region may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: /v2/volumes?region=nyc1

By Name

It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume’s name as a query parameter to /v2/volumes?name=$VOLUME_NAME. Note: You can only create one volume per region with the same name.

By Name and Region

It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume’s name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.

Parameters

Name Type Required Description Default Value
name string False The block storage volume’s name.
region string False The slug identifier for the region where the resource is available.
per_page integer False Number of items returned per page 20
page integer False Which ‘page’ of paginated results to return. 1

Request Sample

import os
from pydo import Client

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

resp = client.volumes.list(region="nyc3")

Responses

See the API spec for this endpoint to view additional detail on responses, headers, parameters, and more.

The response will be a JSON object with a key called volumes. This will be set to an array of volume objects, each of which will contain the standard volume attributes.

Click to expand an example response for All Volumes. 
{
  "value": {
    "volumes": [
      {
        "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
        "region": {
          "name": "New York 1",
          "slug": "nyc1",
          "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-192gb"
          ],
          "features": [
            "private_networking",
            "backups",
            "ipv6",
            "metadata"
          ],
          "available": true
        },
        "droplet_ids": [],
        "name": "example",
        "description": "Block store for examples",
        "size_gigabytes": 10,
        "created_at": "2016-03-02T17:00:49Z",
        "filesystem_type": "ext4",
        "filesystem_label": "example",
        "tags": [
          "aninterestingtag"
        ]
      },
      {
        "id": "506f78a4-e098-11e5-ad9f-000f53305eb2",
        "region": {
          "name": "New York 3",
          "slug": "nyc3",
          "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-192gb"
          ],
          "features": [
            "private_networking",
            "backups",
            "ipv6",
            "metadata"
          ],
          "available": true
        },
        "droplet_ids": [],
        "name": "example",
        "description": "Block store for examples",
        "size_gigabytes": 10,
        "created_at": "2016-03-02T17:01:49Z",
        "filesystem_type": "ext4",
        "filesystem_label": "example",
        "tags": [
          "aninterestingtag"
        ]
      }
    ],
    "links": {},
    "meta": {
      "total": 2
    }
  }
}
Click to expand an example response for Filtered by Name. 
{
  "value": {
    "volumes": [
      {
        "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
        "region": {
          "name": "New York 1",
          "slug": "nyc1",
          "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-192gb"
          ],
          "features": [
            "private_networking",
            "backups",
            "ipv6",
            "metadata"
          ],
          "available": true
        },
        "droplet_ids": [],
        "name": "example",
        "description": "Block store for examples",
        "size_gigabytes": 10,
        "created_at": "2016-03-02T17:00:49Z",
        "filesystem_type": "ext4",
        "filesystem_label": "example",
        "tags": [
          "aninterestingtag"
        ]
      }
    ],
    "links": {},
    "meta": {
      "total": 1
    }
  }
}
Click to expand an example response for Filtered by Region. 
{
  "value": {
    "volumes": [
      {
        "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
        "region": {
          "name": "New York 1",
          "slug": "nyc1",
          "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-192gb"
          ],
          "features": [
            "private_networking",
            "backups",
            "ipv6",
            "metadata"
          ],
          "available": true
        },
        "droplet_ids": [],
        "name": "example",
        "description": "Block store for examples",
        "size_gigabytes": 10,
        "created_at": "2016-03-02T17:00:49Z",
        "filesystem_type": "ext4",
        "filesystem_label": "example",
        "tags": [
          "aninterestingtag"
        ]
      }
    ],
    "links": {},
    "meta": {
      "total": 1
    }
  }
}

Unauthorized

Click to expand an example response. 
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

API Rate limit exceeded

Click to expand an example response. 
{
  "id": "too_many_requests",
  "message": "API Rate limit exceeded."
}

Server error.

Click to expand an example response. 
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

Unexpected error

Click to expand an example response. 
{
  "id": "example_error",
  "message": "some error message"
}
Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support