Get All Instance Info

Get All Instances Info - Overview

The Z-Series Instances API allows authenticated users to retrieve all Z-Series GPU virtual machines associated with their Dataoorts account, along with a summary of instance counts by status.

The endpoint returns individual instance records containing the local instance ID, provider VID, GPU model, current status, SSH command, hourly GPU cost, launch time, and hardware specifications. It also provides summary counts for active, hibernated, pending, terminated, and total instances.

Use this endpoint to monitor Z-Series infrastructure, review GPU configurations, track instance statuses, and integrate instance information into custom dashboards or infrastructure management workflows.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/zseries/instances`
Full URL	`https://cloud.dataoorts.com/api/v1/zseries/instances`
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.

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 Z-Series VMs associated with your account:

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

Replace YOUR_API_KEY with your actual Dataoorts Unify API key.

Python Example Implementation

The following example uses the requests library to retrieve all Z-Series instances and display their summary counts, instance details, SSH command availability, hourly costs, and hardware specifications.

Install the required dependency:

pip install requests

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/zseries/instances"


def list_zseries_instances(api_key: str) -> dict | None:
    """
    Retrieve all Z-Series instances and summary counts.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        The JSON response containing instance records and counts,
        or None if the API returns a non-JSON response.

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

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

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_zseries_instances(api_key)

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

            counts = result.get("counts", {})

            print("\nInstance Summary")
            print("Active:", counts.get("active", 0))
            print("Hibernated:", counts.get("hibernated", 0))
            print("Pending:", counts.get("pending", 0))
            print("Terminated:", counts.get("terminated", 0))
            print("Total:", counts.get("total", 0))

            print("\nInstance Records")

            for instance in result.get("data", []):
                specs = instance.get("specs", {})

                print("-" * 40)
                print("Instance ID:", instance.get("instance_id"))
                print("Provider VID:", instance.get("provider_vid"))
                print("GPU Model:", instance.get("gpu_model"))
                print("Status:", instance.get("status"))
                print("Hourly Cost:", instance.get("hourly_cost"))
                print("Launch Time:", instance.get("launch_time"))

                # Avoid printing connection details to shared logs.
                print(
                    "SSH Command Available:",
                    bool(instance.get("ssh_command"))
                    and instance.get("ssh_command") != "N/A",
                )

                print("GPUs:", specs.get("gpus"))
                print("vCPUs:", specs.get("vcpus"))
                print("RAM (GB):", specs.get("ram_gb"))
                print("VRAM (GB):", specs.get("vram_gb"))
                print("Storage (GB):", specs.get("storage_gb"))

    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 in your Env before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python zseries_instances.py

Windows PowerShell

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

The script displays the instance counts first, followed by each instance's identifiers, GPU model, status, hourly cost, launch time, SSH command availability, and hardware specifications. It avoids printing the full SSH command to the console.

Example Success Response

A successful request returns a JSON object containing instance counts, individual instance records, a descriptive message, and the response status.

HTTP Status: 200 OK

{
  "counts": {
    "active": 1,
    "hibernated": 0,
    "pending": 0,
    "terminated": 9,
    "total": 10
  },
  "data": [
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 19,
      "launch_time": "Fri, 26 Jun 2026 05:27:29 GMT",
      "provider_vid": "434190",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 800,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "ssh -i temporary.pem -o StrictHostKeyChecking=no [email protected]",
      "status": "Active"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 9,
      "launch_time": "Tue, 09 Jun 2026 09:06:45 GMT",
      "provider_vid": "423649",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 8,
      "launch_time": "Tue, 09 Jun 2026 08:45:33 GMT",
      "provider_vid": "423655",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 7,
      "launch_time": "Tue, 09 Jun 2026 08:43:02 GMT",
      "provider_vid": "423634",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.96,
      "instance_id": 6,
      "launch_time": "Mon, 08 Jun 2026 15:02:32 GMT",
      "provider_vid": "423336",
      "specs": {
        "gpus": 2,
        "ram_gb": 248,
        "storage_gb": 100,
        "vcpus": 56,
        "vram_gb": 48
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 5,
      "launch_time": "Mon, 08 Jun 2026 13:36:43 GMT",
      "provider_vid": "423273",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 4,
      "launch_time": "Mon, 08 Jun 2026 13:25:54 GMT",
      "provider_vid": "423268",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 3,
      "launch_time": "Mon, 08 Jun 2026 13:15:59 GMT",
      "provider_vid": "423263",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.96,
      "instance_id": 2,
      "launch_time": "Mon, 08 Jun 2026 12:22:02 GMT",
      "provider_vid": "423237",
      "specs": {
        "gpus": 2,
        "ram_gb": 248,
        "storage_gb": 100,
        "vcpus": 56,
        "vram_gb": 48
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "gpu_model": "L4",
      "hourly_cost": 0.48,
      "instance_id": 1,
      "launch_time": "Mon, 08 Jun 2026 12:10:25 GMT",
      "provider_vid": "423232",
      "specs": {
        "gpus": 1,
        "ram_gb": 124,
        "storage_gb": 100,
        "vcpus": 28,
        "vram_gb": 24
      },
      "ssh_command": "N/A",
      "status": "terminated"
    }
  ],
  "message": "Z-Series instances list retrieved successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance counts, identifiers, GPU configurations, statuses, connection details, and hourly costs may differ in subsequent API responses.

Response Fields

Top-Level Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`; an unsuccessful response may return `error`.
`message`	String	A descriptive message about the result of the request.
`counts`	Object	Contains summary counts of instances by status.
`data`	Array of objects	Contains the individual Z-Series VM records returned by the API.

Counts Object

The counts object provides an overview of instance states.

Field	Type	Description
`counts.total`	Integer	Total number of Z-Series instances reported.
`counts.active`	Integer	Number of active instances.
`counts.hibernated`	Integer	Number of hibernated instances.
`counts.pending`	Integer	Number of instances reported as pending or provisioning.
`counts.terminated`	Integer	Number of terminated instances.

Instance Object

Each object in the data array represents a Z-Series instance record.

Field	Type	Description
`instance_id`	Integer	The local instance ID assigned to the virtual machine.
`provider_vid`	String	The DC Provider's virtual machine identifier.
`gpu_model`	String	The GPU model associated with the instance.
`status`	String	Current VM status returned by API, such as `Active` or `terminated`.
`ssh_command`	String	The SSH command returned for connecting to the virtual machine, or `N/A` when unavailable.
`hourly_cost`	Float	The hourly GPU VM cost in USD.
`launch_time`	String	The virtual machine launch timestamp.
`specs`	Object	Contains the hardware specs associated with the virtual machine.

Hardware Specification Fields

The specs object contains the hardware configuration reported for each instance.

Field	Type	Description
`specs.gpus`	Integer	Number of GPUs allocated to the virtual machine.
`specs.vcpus`	Integer	Total number of vCPU cores.
`specs.ram_gb`	Integer	Total RAM capacity in GB.
`specs.vram_gb`	Integer	Total GPU VRAM capacity in GB.
`specs.storage_gb`	Integer	Allocated NVMe storage capacity in GB.

Understanding Instance Information

Instance Status

The status field indicates the state reported for each virtual machine. The example response includes Active and terminated instances, while the summary also provides hibernated and pending counts.

Pending and provisioning virtual machines are grouped together under counts.pending.

Use the returned status to categorize instances in your application. The counts object provides the summary, while individual records contain their own status values.

SSH Command Availability

The ssh_command field provides the SSH command returned by the API.

In the example response, Active instance includes an SSH command, while terminated instances return N/A.

The returned command can be used with the downloaded temporary.pem private key once the virtual machine is available. Keep the private key and connection details secure.

Instance Ordering

Instances are returned in descending order of creation, with the newest instances appearing first.

Hardware Specifications

The specs object provides the GPU count, vCPUs, RAM, VRAM, and allocated NVMe storage capacity reported for each VMs. Use these fields when displaying hardware details or comparing instance configurations.

Hourly Cost

The hourly_cost field reports the hourly GPU cost for the virtual machine in USD. Use the returned value when displaying cost information. Refer to the applicable billing details for exact charging rules.

Important Notes

1. Authenticated User: This endpoint returns all Z-Series virtual machines belonging to the authenticated user.

2. Instance Ordering: Instances are returned in descending order of creation, with the newest instances first.

3. Status Counts: The counts object provides a summary of active, hibernated, pending, terminated, and total instances. Pending and provisioning instances are grouped under pending.

4. Instance Status: The response may contain active, hibernated, pending, and terminated instances. Do not assume every returned instance is currently running.

5. SSH Availability: The ssh_command field may return an SSH command or N/A. Use the command only when the virtual machine is available for connection.

6. SSH Security: The returned ssh_command can be used with the downloaded temporary.pem private key. Keep the private key and connection information secure.

7. Pricing Currency: All hourly pricing values are returned in USD.

8. Empty Results: If the account has no Z-Series GPU VM Instances, the data array will be empty and all count values will be 0.

9. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

API may return unsuccessful HTTP status code & JSON error response when a request cannot be completed.

Your application should handle authentication failures, network errors, request timeouts, server errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type and handles JSON decoding errors before processing the instance records.

Missing API Key

HTTP Status: 401 Unauthorized

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Include the Authorization header with a valid Bearer token.

Missing Token

HTTP Status: 401 Unauthorized

{
  "status": "error",
  "message": "API Token is missing or empty."
}

Ensure that the API token is present and non-empty.

Invalid API Key

HTTP Status: 403 Forbidden

{
  "status": "error",
  "message": "Unauthorized: Invalid API key."
}

Verify that your Dataoorts API key is valid and included in the request header.

Internal Server Error

HTTP Status: 500 Internal Server Error

{
  "status": "error",
  "message": "Internal Server Error, Please Contact Support."
}

If the error persists, contact the Dataoorts support team for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include the `Authorization` header with a valid Bearer token.
API token is empty	Set a non-empty `DATAOORTS_API_KEY` environment variable.
API key is invalid	Verify the API key through the Dataoorts platform.
HTTP request fails	Catch `requests.exceptions.RequestException` and inspect the response error details.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.
No instances are returned	Check `counts` and `data`; an empty array and zero counts indicate no instances are associated with the account.
SSH command is `N/A`	Check the instance status before attempting to connect.

Get Help and Support

For assistance with Z-Series VM information or API integration, Contact support team at [email protected].