All Instances Info

This endpoint retrieves a comprehensive list of all Nova Series GPU virtual machine instances associated with the user's account, along with aggregate status counts and detailed configuration metrics for each instance.

Get All Instances Info - Overview

The Nova Series Instances API allows authenticated users to retrieve detailed information and current status for all instances associated with their Dataoorts account.

The endpoint returns a summary of instance counts by status, along with individual instance records containing GPU configuration, instance ID, public IP, region, pricing contract, hourly cost, and hardware specifications.

Use this endpoint to monitor your Nova infrastructure, review running and terminated instances, track instance configurations, and integrate instance information into custom dashboards or automation workflows.

Endpoint

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

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 Nova instance records:

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/nova/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 Nova instances and display their summary counts and individual instance details.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def list_nova_instances(api_key: str) -> dict:
    """
    Retrieve all Nova instance records and status counts.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response containing instance records
              and status counts.

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

        print("Status:", result.get("status"))

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

        print("\nInstance Summary")
        print("Running:", counts.get("running", 0))
        print("Stopped:", counts.get("stopped", 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("Name:", instance.get("name"))
            print("Status:", instance.get("status"))
            print("Contract:", instance.get("contract"))
            print("Hourly Cost:", instance.get("hourly_cost"))
            print("Public IP:", instance.get("public_ip"))
            print("Region:", instance.get("region"))
            print("GPU Count:", specs.get("gpu"))
            print("CPU Cores:", specs.get("cpu"))
            print("RAM:", specs.get("ram"))
            print("VRAM:", specs.get("vram"))
            print("Storage:", specs.get("storage"))

    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 nova_instances.py

Windows PowerShell

PowerShell

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

The script prints the instance summary first, followed by the configuration, status, pricing, region, and hardware details for each returned instance.

Example Success Response

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

HTTP Status: 200 OK

JSON

{
  "counts": {
    "running": 1,
    "stopped": 0,
    "terminated": 14,
    "total": 15
  },
  "data": [
    {
      "contract": "on-demand",
      "hourly_cost": 2.6335,
      "instance_id": 432,
      "name": "1x H100 SXM5 80GB",
      "public_ip": "86.38.238.11",
      "region": "FIN-02",
      "specs": {
        "cpu": 32,
        "gpu": 1,
        "ram": 185,
        "storage": 150,
        "vram": 80
      },
      "status": "terminated"
    },
    {
      "contract": "on-demand",
      "hourly_cost": 2.6335,
      "instance_id": 430,
      "name": "1x H100 SXM5 80GB",
      "public_ip": "95.133.252.78",
      "region": "FIN-03",
      "specs": {
        "cpu": 32,
        "gpu": 1,
        "ram": 185,
        "storage": 150,
        "vram": 80
      },
      "status": "running"
    }
  ],
  "status": "success"
}

The example is abbreviated to show two instance records. The actual response may contain additional records, and the counts reflect the values returned by the API.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
counts	Object	Contains summary counts for the instance statuses and the total number of instances reported.
data	Array of objects	Contains the individual Nova instance records returned by the API.

Instance Counts

The counts object provides a summary of instance states.

Field	Type	Description
counts.running	Integer	Number of instances reported as running.
counts.stopped	Integer	Number of instances reported as stopped.
counts.terminated	Integer	Number of instances reported as terminated.
counts.total	Integer	Total number of instances reported in the summary.

Use these values to display an overview of your Nova infrastructure in dashboards and monitoring tools.

Instance Record Fields

Each object in the data array represents an instance record.

Field	Type	Description
instance_id	Integer	The identifier assigned to the instance.
name	String	The display name or GPU configuration name of the instance.
status	String	The instance status reported by the API, such as running or terminated.
contract	String	The pricing contract associated with the instance, such as on-demand or spot.
hourly_cost	Float	The hourly cost reported for the instance.
public_ip	String	The public IP address associated with the instance. May be N/A when an IP address is unavailable or not applicable.
region	String	The region in which the instance is or was deployed.
specs	Object	Contains the hardware specifications reported for the instance.

Hardware Specification Fields

The specs object contains the reported hardware configuration of the instance.

Field	Type	Description
specs.gpu	Integer	Number of GPUs associated with the instance.
specs.cpu	Integer	Number of CPU cores reported for the instance.
specs.ram	Number	RAM capacity reported by the API.
specs.vram	Number	GPU video memory capacity reported by the API.
specs.storage	Number	Storage capacity reported for the instance.

The example response provides numerical values for RAM, VRAM, and storage. Refer to the corresponding instance configuration details for their applicable units.

Understanding Instance Records

Instance Status

The status field indicates the state reported by the API for each instance. The example response includes running and terminated instances.

Use the returned status to categorize records in your application or display the current state of your Nova resources.

On-Demand and Spot Contracts

The contract field identifies the instance's pricing contract:

• on-demand — An On-Demand instance contract.
• spot — A Spot instance contract.

Use this field to distinguish contract types when displaying or reviewing instance information.

Public IP Availability

Some records may return N/A for public_ip. Handle this value appropriately in your application instead of treating it as a valid IP address.

Historical Instance Records

The response may include terminated instances alongside running or stopped instances. Do not assume that every record represents an active, currently running virtual machine.

Important Notes

1. Status Counts: Use the values in counts to display the summary provided by the API. Do not assume every returned instance is running.

2. Pricing Information: The hourly_cost field reports the hourly cost returned by the API. Consult the applicable Dataoorts billing details for exact charging rules.

3. Nullable or Unavailable Values: Handle values such as N/A in public_ip gracefully.

4. Current State: Instance status and other details reflect the information returned at the time of the request. Retrieve the latest response when current state is important.

5. Instance Identification: Use instance_id to identify a record when calling an endpoint that accepts the Nova instance ID.

Error Handling

If the request fails, the API may return an unsuccessful HTTP status code and a 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 Nova instance information or API integration, contact the Dataoorts support team at [email protected].