Get All Instance Info

Get All Instance Info - Overview

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

The endpoint returns a summary of instance counts by status, along with individual instance records containing the instance ID, hostname, GPU configuration, hourly cost, public IP address, deployment region, operating system image, provider VM ID, and hardware specifications.

Use this endpoint to monitor Orion infra, review active and terminated instances, track resource configurations, and integrate instance information into custom dashboards or infrastructure management workflows.

Endpoint

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

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

Install the required dependency:

pip install requests

import os
import requests


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


def list_orion_instances(api_key: str) -> dict:
    """
    Retrieve all Orion 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_orion_instances(api_key)

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

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

        print("\nInstance Summary")
        print("Running:", counts.get("running", 0))
        print("Pending:", counts.get("pending", 0))
        print("Terminated:", counts.get("terminated", 0))
        print("Other:", counts.get("other", 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("Hostname:", instance.get("hostname"))
            print("Name:", instance.get("name"))
            print("Status:", instance.get("status"))
            print("Hourly Cost:", instance.get("hourly_cost"))
            print("Public IP:", instance.get("public_ip"))
            print("Region:", instance.get("region"))
            print("OS Image:", instance.get("os_image"))
            print("GPU Count:", specs.get("gpu_count"))
            print("CPU Cores:", specs.get("cpu_cores"))
            print("RAM (GB):", specs.get("ram_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 before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python orion_instances.py

Windows PowerShell

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

Script displays summary counts first, followed by details and hardware specifications of each returned instance.

Example Success Response

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

HTTP Status: 200 OK

{
  "counts": {
    "other": 1,
    "pending": 0,
    "running": 0,
    "terminated": 4,
    "total": 5
  },
  "data": [
    {
      "hostname": "inst-233d51a98bb44fc492e0",
      "hourly_cost": 2.5725,
      "instance_id": 51,
      "launch_time": "Wed, 28 Jan 2026 09:39:46 GMT",
      "name": "H200 x1",
      "os_image": "ubuntu22.04_cuda12.4_shade_os",
      "provider_vmid": "sf-6979d963dbe948d5b8ff3afe",
      "public_ip": "N/A",
      "region": "kansascity-usa-4",
      "specs": {
        "cpu_cores": 16,
        "gpu_count": 1,
        "ram_gb": 200,
        "storage_gb": 465
      },
      "status": "terminated"
    },
    {
      "hostname": "inst-ae3ea7dec73f4986a452",
      "hourly_cost": 2.5725,
      "instance_id": 50,
      "launch_time": "Wed, 28 Jan 2026 09:36:22 GMT",
      "name": "H200 x1",
      "os_image": "ubuntu22.04_cuda12.4_shade_os",
      "provider_vmid": "sf-6979d897dbe948d5b8ff1ec6",
      "public_ip": "204.12.171.93",
      "region": "kansascity-usa-4",
      "specs": {
        "cpu_cores": 16,
        "gpu_count": 1,
        "ram_gb": 200,
        "storage_gb": 465
      },
      "status": "active"
    }
  ],
  "message": "Orion instances list retrieved for you successfully.",
  "status": "success"
}

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

Response Fields

Field	Type	Description
`status`	String	Show Result of the request, Successful response returns `success`.
`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 Orion instance records returned by the API.

Instance Counts

The counts object provides a summary of the instance states reported by the API.

Field	Type	Description
`counts.running`	Integer	Number of instances reported as running in the summary.
`counts.pending`	Integer	Number of instances reported as pending in the summary.
`counts.terminated`	Integer	Number of instances reported as terminated in the summary.
`counts.other`	Integer	Number of instances grouped under other statuses in summary.
`counts.total`	Integer	Total number of instances reported in the summary.

Use these values to display an overview of your Orion infrastructure.

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.
`hostname`	String	The hostname returned for 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 `active` or `terminated` in the example.
`hourly_cost`	Float	The hourly cost reported for the instance.
`public_ip`	String	The public IP address associated with the instance. May contain `N/A` when an address is unavailable or not applicable.
`region`	String	The deployment region associated with the instance.
`os_image`	String	The operating system image identifier associated with the instance.
`provider_vmid`	String	The virtual machine identifier returned by the underlying provider.
`launch_time`	String	The launch timestamp reported for the instance.
`specs`	Object	Contains the hardware specifications reported for the instance.

Hardware Specification Fields

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

Field	Type	Description
`specs.gpu_count`	Integer	Number of GPUs associated with the instance.
`specs.cpu_cores`	Integer	Number of CPU cores reported for the instance.
`specs.ram_gb`	Number	System RAM capacity in GB.
`specs.storage_gb`	Number	Storage capacity reported for the instance in GB.

Understanding Instance Information

Instance Status

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

The summary counts use separate Instance status categories, including running, pending, terminated, and other. Use the values returned by the API rather than assuming the record-level status labels always match the summary category names.

Public IP Address

The public_ip field contains the IP address returned for the instance. Some records may contain N/A, indicating that a usable public IP address is not provided in that record.

Your application should handle this value appropriately rather than treating it as a valid IP address.

Pricing Information

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

Historical Instance Records

The response may include terminated instances alongside active or other instances. Do not assume that every returned record represents a currently running virtual machine.

Important Notes

1. Status Summary: Use the counts object to display the status summary returned by the API. Record-level status values may use labels such as active, so handle statuses as returned.

2. Public IP Availability: Handle N/A values in public_ip rather than treating them as valid IP addresses.

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

4. Hardware Specifications: Use specs object to display GPU count, CPU cores, RAM, & storage information.

5. 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.

6. Instance Identification: Use instance_id when calling the other Orion endpoints that require an GPU instance identifier.

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/HTTPX status codes. Do not assume that an error response contains the same fields as a successful response.

Get Help and Support

For assistance with Orion instance info or API integration, Contact the support team at [email protected].