Get All Instance Info

Get All Instance Info - Overview

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

The endpoint returns a summary of instance counts by status, along with individual instance records containing the instance ID, machine type, hourly cost, launch time, SSH command, and hardware specifications.

Use this endpoint to monitor Orix infrastructure, track instance provisioning, review terminated instances, and integrate instance information into custom dashboards or infrastructure management workflows.

Endpoint

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

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/orix/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 Orix instances and display their summary counts, instance details, and hardware specifications.

Install the required dependency:

pip install requests

import os
import requests


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


def list_orix_instances(api_key: str) -> dict:
    """
    Retrieve all Orix 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=60,
    )

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

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

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

        print("\nInstance Summary")
        print("Active:", counts.get("active", 0))
        print("Provisioning:", counts.get("provisioning", 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("Machine Type:", instance.get("machine_type"))
            print("Status:", instance.get("status"))
            print("Hourly Cost:", instance.get("hourly_cost"))
            print("Launch Time:", instance.get("launch_time"))
            print("SSH Command:", instance.get("ssh_command"))
            print("GPU Count:", specs.get("gpu_count"))
            print("vCPUs:", specs.get("vcpu"))
            print("DRAM (GB):", specs.get("dram"))
            print("NVMe Storage (GB):", specs.get("nvme"))

    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

export DATAOORTS_API_KEY="YOUR_API_KEY"
python orix_instances.py

Windows PowerShell

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

The script displays the instance counts first, followed by the machine type, status, hourly cost, launch time, SSH command, and hardware specifications for each returned instance.

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": 0,
    "provisioning": 1,
    "terminated": 3,
    "total": 4
  },
  "data": [
    {
      "hourly_cost": 33.42,
      "instance_id": 4,
      "launch_time": "Wed, 30 Sep 2026 05:41:29 GMT",
      "machine_type": "vm-h200",
      "specs": {
        "dram": 2048,
        "gpu_count": 8,
        "nvme": 14307,
        "vcpu": 224
      },
      "ssh_command": "Pending",
      "status": "provisioning"
    },
    {
      "hourly_cost": 33.52,
      "instance_id": 3,
      "launch_time": "Wed, 30 Sep 2026 03:14:49 GMT",
      "machine_type": "vm-h200",
      "specs": {
        "dram": 2048,
        "gpu_count": 8,
        "nvme": 14307,
        "vcpu": 224
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "hourly_cost": 5.08,
      "instance_id": 2,
      "launch_time": "Sat, 26 Sep 2026 13:37:18 GMT",
      "machine_type": "vm-h100",
      "specs": {
        "dram": 240,
        "gpu_count": 1,
        "nvme": 720,
        "vcpu": 20
      },
      "ssh_command": "N/A",
      "status": "terminated"
    },
    {
      "hourly_cost": 3.34,
      "instance_id": 1,
      "launch_time": "Sat, 26 Sep 2026 13:35:42 GMT",
      "machine_type": "vm-h100",
      "specs": {
        "dram": 240,
        "gpu_count": 1,
        "nvme": 720,
        "vcpu": 20
      },
      "ssh_command": "N/A",
      "status": "terminated"
    }
  ],
  "message": "Orix-Series GPU Instances List Retrieved Successfully.",
  "status": "success"
}

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

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful API response returns `success` status.
`message`	String	A descriptive message about the result of the request.
`counts`	Object	Contains summary counts for instance statuses and the total number of instances reported.
`data`	Array of objects	Contains Individual Orix Instance records returned by the API.

Instance Counts

The counts object provides an overview of instance states.

Field	Type	Description
`counts.active`	Integer	Number of instances reported as active in the summary.
`counts.provisioning`	Integer	Number of instances reported as provisioning.
`counts.terminated`	Integer	Number of instances reported as terminated.
`counts.total`	Integer	Total number of instances reported in the summary.

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.
`machine_type`	String	The machine type or config name, such as `vm-h200` or `vm-h100`.
`status`	String	The Instance status returned, such as `provisioning` or `terminated`.
`hourly_cost`	Float	The hourly cost reported for the Instance.
`launch_time`	String	The launch timestamp reported for the instance.
`ssh_command`	String	The SSH connection command or SSH availability value returned by the API. It may contain `Pending` / `pending` or `N/A`.
`specs`	Object	Contains the hardware specifications reported for the instance.

Hardware Specification Fields

The specs object contains the hardware configuration associated with each instance.

Field	Type	Description
`specs.gpu_count`	Integer	Number of GPUs associated with the instance.
`specs.vcpu`	Integer	Number of virtual CPU cores reported for the instance.
`specs.dram`	Number	DRAM capacity reported by the API.
`specs.nvme`	Number	NVMe storage capacity reported by the API.

The example response provides values for dram and nvme without explicitly specifying their units. Refer to the relevant Orix configuration details when interpreting those values.

Understanding Instance Information

Instance Status

The status field indicates the state reported for each instance. The example response includes provisioning and terminated records.

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

SSH Command Availability

The ssh_command field contains the connection command or availability value returned by the API.

In the example response:

Pending or pending is returned for an instance with a provisioning status.
N/A is returned for terminated instances.

Check the latest Instance status and SSH Information before attempting to build SSH connection. Do not treat Pending or N/A as executable SSH commands.

Hourly Cost - Pre 10 Minute Cycle

The hourly_cost field reports the hourly cost associated with an instance. Use this value to display pricing information, while referring to applicable billing details for exact charging rules.

Important Notes

1. Provisioning Status: An instance with a provisioning status may not yet be ready for use. Check its status and SSH command again when needed.

2. SSH Availability: Handle Pending / pendingand N/A values in ssh_command appropriately. Only use a valid SSH command when the instance is ready for connection.

3. Historical Records: The response can contain terminated instances alongside instances that are still provisioning or active. Do not assume every returned record is currently running.

4. Hardware Specifications: Use specs object to display GPU count, vCPUs, DRAM, and NVMe storage values.

5. Pricing Information: The hourly_cost field represents the cost returned by the API. Consult the applicable billing details for exact charging rules.

6. Current State: Instance details reflect the information returned at the time of the request. Retrieve the latest information when current status or connection availability is important.

Error Handling

If request fails, API may return unsuccessful HTTP status code & 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 every response contains the same fields as a successful response.

Get Help and Support

For assistance with Orix instance information or API integration, Contact support team at [email protected].