List All Volumes

This endpoint retrieves a comprehensive list of all persistent storage volumes across all cloud regions associated with the user's account, including their current status and attachment details.

List All NVMe Volumes - Overview

The X-Series Volume Listing API allows authenticated users to retrieve all volumes associated with their Dataoorts account across available regions, along with their current status and storage details.

The endpoint returns a list of volumes, including their volume IDs, display IDs, storage capacity, region, hourly cost, attachment information, and current status.

Use this endpoint to manage storage resources, monitor volume attachment states, review storage costs, and integrate volume information into custom infrastructure dashboards or automation workflows.

Endpoint

Property	Value
HTTP Method	GET
Endpoint	/xseries/volumes
Full URL	https://cloud.dataoorts.com/api/v1/xseries/volumes
Authentication	Bearer Token
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

HTTP

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

This endpoint does not require any query parameters or a request body. Send a GET request with the required authentication header.

Request Examples

cURL - Use the following command to retrieve all volumes associated with your account:

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Replace YOUR_API_KEY with your actual Dataoorts Unify API key.

---

Python Example Implementation

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/xseries/volumes"


def list_xseries_volumes(api_key: str) -> dict:
    """
    Retrieve all volumes associated with the authenticated account.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response containing volume records.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response cannot be decoded as JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
    }

    response = requests.get(
        API_URL,
        headers=headers,
        timeout=30,
    )

    response.raise_for_status()

    try:
        return response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = list_xseries_volumes(api_key)

        print("Status:", result.get("status"))
        print("Count:", result.get("count"))
        print("Message:", result.get("message"))

        print("\nVolumes:")

        for volume in result.get("data", []):
            print("-" * 40)
            print("Volume ID:", volume.get("volume_id"))
            print("Display ID:", volume.get("display_id"))
            print("Size (GB):", volume.get("size_gb"))
            print("Region:", volume.get("region"))
            print("Status:", volume.get("status"))
            print("Hourly Cost:", volume.get("hourly_cost"))
            print(
                "Attached Instance ID:",
                volume.get("attached_to_instance_id"),
            )

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid API response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python list_volumes.py

Windows PowerShell

PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python list_volumes.py

The script displays the response status, total volume count, and the details of each returned volume.

Example Success Response

A successful request returns a JSON object containing the total number of volumes, a descriptive message, and an array of volume records.

HTTP Status: 200 OK

JSON

{
  "count": 1,
  "data": [
    {
      "attached_to_instance_id": null,
      "display_id": "SSD-0729160",
      "hourly_cost": 0.067742,
      "region": "CANADA-1",
      "size_gb": 100,
      "status": "detached",
      "volume_id": "29160"
    }
  ],
  "message": "volumes retrieved successfully.",
  "status": "success"
}

The values shown above illustrate the response structure. The number of volumes and their details depend on the records returned by the API.

Response Fields

Field	Type	Description
status	String	Indicates result of the API request. A successful response returns success.
count	Integer	The number of volume records returned by the API.
message	String	A descriptive message about the result of the request.
data	Array of objects	Contains the volume records associated with the authenticated account.
data[].volume_id	String	The identifier assigned to the volume.
data[].display_id	String	The human-readable display identifier associated with the volume.
data[].size_gb	Integer	The volume's storage capacity in GB.
data[].region	String	Region in which volume was created.
data[].status	String	The current volume status reported by the API, such as detached in the example response.
data[].hourly_cost	Float	The hourly cost reported for the volume.
data[].attached_to_instance_id	Integer or null	The ID of the instance to which the volume is attached, or null when no instance ID is associated with it.

Understanding Volume Status

The status field indicates the volume state reported by the API.

For example, the response may contain:

• detached — The volume is reported as detached from an instance.
• Other statuses, if returned by the API, should be interpreted according to their actual values and the applicable Dataoorts volume lifecycle rules.

The attached_to_instance_id field provides additional information about the volume's attachment. A null value indicates that no instance ID is associated with the volume in the returned record.

Understanding Volume Costs

The hourly_cost field reports the hourly cost associated with each volume.

Use this field to display storage costs in dashboards or estimate storage expenses. The value shown in the response should be treated as the cost reported by the API; consult the applicable Dataoorts billing details for the exact charging rules.

Using Volume Information in Workflows

You can use this endpoint to:

1. Retrieve the volumes associated with your account.
2. Identify each volume using its volume_id or display_id.
3. Review its capacity, region, and current status.
4. Check the reported attachment information.
5. Display volume details and hourly costs in your application.

Important: This endpoint retrieves volume information. It does not create, attach, detach, or delete volumes.

Important Notes

1. Region Compatibility: A volume can only be attached to a GPU instance located in the same region. Verify the region of both resources before attempting to attach a volume.

2. Volume Identification: Store the returned volume_id and display_id when you need to reference a volume in subsequent workflows.

3. Nullable Fields: The attached_to_instance_id field may be null. Your application should handle null values rather than assuming every volume is attached to an instance.

4. Cost Handling: Treat hourly_cost as a numeric value when performing calculations, and apply the relevant currency and billing rules provided by Dataoorts.

5. Current Status: The status reflects the information returned at the time of the request. Retrieve the latest volume information when current attachment state is important.

Error Handling

If request fails, API may return unsuccessful HTTP status code and JSON response containing an error message.

Your application should handle authentication failures, network errors, request timeouts, server errors, and unexpected response formats. The exact error codes and messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that an error response contains the same fields as a successful response.

Get Help and Support

For assistance with volume management, storage information, or API integration, contact the Dataoorts support team at [email protected].