Single Instance Info

Single Instance Info - Overview

The Orion Series Instance Info API allows authenticated users to retrieve detailed information and the current status of a specific Orion instance using its instance ID, public IP address, or DC Provider Instance ID.

The endpoint returns instance information such as the hostname, GPU configuration, hourly cost, operating system image, deployment region, public IP address, SSH connection details, and launch time. It also includes hardware specifications and billing information when available.

Use this endpoint to monitor individual instances, retrieve configuration details, check instance status, and integrate instance information into custom dashboards or infrastructure management workflows.

Response may also contain historical information for terminated instances, as illustrated in example response.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/orion/instance`
Full URL	`https://cloud.dataoorts.com/api/v1/orion/instance`
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 accepts a required query parameter.

Parameter	Type	Required	Description
`id_or_ip`	String	Yes	The instance ID, public IP address, or DC Provider Instance ID of the Instance whose information you want to retrieve.

Provide identifier of the intended instance, Ensure that the supplied value corresponds to the correct instance.

Request Examples

cURL — Using Instance ID

Use the following command to retrieve information about an Orion instance using its instance ID:

curl --get \
  --url "https://cloud.dataoorts.com/api/v1/orion/instance" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --data-urlencode "id_or_ip=51"

cURL — Using Public IP Address

You can also retrieve instance information using its public IP address:

curl --get \
  --url "https://cloud.dataoorts.com/api/v1/orion/instance" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --data-urlencode "id_or_ip=95.133.252.78"

cURL — Using Provider Instance ID

To look up an instance using its provider VM ID, supply that identifier through the same query parameter:

curl --get \
  --url "https://cloud.dataoorts.com/api/v1/orion/instance" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --data-urlencode "id_or_ip=DC_Provider_Instance_ID"

Replace YOUR_API_KEY and the example identifier with your actual values.

Python Example Implementation

Following example uses the requests library to retrieve instance information and display the returned details.

Install the required dependency:

pip install requests

import os
import json
import requests


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


def get_orion_instance_info(
    api_key: str,
    id_or_ip: str,
) -> dict:
    """
    Retrieve information about a specific Orion instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_ip: The instance ID, public IP address, or provider VM ID.

    Returns:
        dict: The JSON response containing instance information.

    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",
    }

    params = {
        "id_or_ip": id_or_ip,
    }

    response = requests.get(
        API_URL,
        headers=headers,
        params=params,
        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 = get_orion_instance_info(
            api_key=api_key,
            id_or_ip="51",
        )

        print(json.dumps(result, indent=2))

        instance = result.get("data", {})
        specs = instance.get("specs", {})

        print("\nInstance Summary")
        print("Instance ID:", instance.get("instance_id"))
        print("Hostname:", instance.get("hostname"))
        print("Name:", instance.get("name"))
        print("Status:", instance.get("status"))
        print("Public IP:", instance.get("public_ip"))
        print("Region:", instance.get("region"))
        print("Hourly Cost:", instance.get("hourly_cost"))
        print("OS Image:", instance.get("os_image"))

        print("\nHardware Specifications")
        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_instance_info.py

Windows PowerShell

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

To retrieve information using a public IP address or provider VM ID, replace "51" in the function call with the appropriate identifier.

Example Success Response

A successful request returns a JSON object containing the instance details under data, along with a descriptive message and the overall response status.

HTTP Status: 200 OK

{
  "data": {
    "hostname": "inst-233d51a98bb44fc492e0",
    "hourly_cost": 2.5725,
    "instance_id": 51,
    "launch_time": "Wed, 28 Jan 2026 09:39:46 GMT",
    "name": "H200 x1",
    "next_billing_cycle": null,
    "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
    },
    "ssh_password": "orion",
    "ssh_user": "orion",
    "status": "terminated"
  },
  "message": "Terminated instance history retrieved for you successfully.",
  "status": "success"
}

The values above illustrate the response structure. The actual instance information and message depend on the instance being queried and its state.

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`.
`message`	String	A descriptive message about the result, such as retrieving terminated instance history.
`data`	Object	Contains the details of the requested Orion instance.
`data.instance_id`	Integer	The identifier assigned to the instance.
`data.hostname`	String	The hostname returned for the instance.
`data.name`	String	The instance's display name or GPU configuration name.
`data.status`	String	The instance status reported by the API, such as `terminated` in the example.
`data.hourly_cost`	Float	The hourly cost reported for the instance.
`data.public_ip`	String	The public IP address returned for the instance. May contain `N/A` when an address is unavailable or not applicable.
`data.region`	String	The deployment region associated with the instance.
`data.provider_vmid`	String	The virtual machine identifier returned by the underlying provider.
`data.os_image`	String	The operating system image identifier associated with the instance.
`data.launch_time`	String	The launch timestamp reported by the API.
`data.next_billing_cycle`	String or `null`	The next billing cycle value, or `null` when no value is provided.
`data.ssh_user`	String	The SSH username returned for the instance.
`data.ssh_password`	String	The SSH password returned by the API. Treat this value as a sensitive credential.
`data.specs`	Object	Contains the hardware specifications returned for the instance.

Hardware Specification Fields

The data.specs object contains the hardware details reported for the 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 data.status field indicates the instance state reported by the API. In the example response, the status is terminated.

The endpoint may return historical information for terminated instances. Do not assume that every successful response represents an active or running instance.

Public IP Address

The data.public_ip field contains the returned public IP address. In the example response, its value is N/A.

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

Billing Information

The hourly_cost field reports the hourly cost returned by the API. The next_billing_cycle field may contain a timestamp or null.

Use these values as returned by the service when displaying instance information. Consult the applicable Dataoorts billing details for the precise charging rules.

SSH Credentials

The response may contain ssh_user and ssh_password. Treat both fields as sensitive connection information. Avoid printing credentials in production logs, exposing them to unauthorized users, or storing them in unsecured locations.

Important Notes

1. Correct Identifier: The id_or_ip parameter can be used with the instance ID, public IP address, or provider VM ID, as indicated by the endpoint's usage example.

2. Historical Records: A successful response may contain details for a terminated instance. Check data.status before assuming that the instance is operational.

3. Nullable Fields: Fields such as next_billing_cycle may be null, and public_ip may contain N/A. Handle these values in your application.

4. Sensitive Credentials: Protect ssh_password & other returned connection details as confidential credentials.

5. Current State: Instance details reflect the information returned by the API at the time of the request.

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, invalid instance identifiers, 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 Orion Instance info or API integration, contact the support team at [email protected].