Get Single Instance Info

Get Single Instance Info - Overview

The X-Series Instance Info API allows authenticated users to retrieve detailed information about a specific virtual machine using its Instance ID or IP address.

The endpoint returns information about the instance's current state, configuration, operating system image, public IP address, SSH port, hourly cost, storage, and billing details. It also includes host node information, such as the node identifier, node type, provider, and launch date.

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

Endpoint

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

The instance lookup is performed using a query parameter.

Parameter	Type	Required	Description
`id_or_ip`	String	Yes	The Instance ID or IP address of the Instance whose live Information you want to retrieve.

Provide either the instance's identifier or its IP address, The value must correspond to an instance accessible through your account.

Request Examples

cURL - Retrieve instance information using an Instance ID:

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

Alternatively, use the instance's IP address:

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

Replace YOUR_API_KEY with your actual Dataoorts API key & supply the appropriate Instance ID or IP address.

Python Example Implementation:

import os
import requests


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


def get_xseries_instance(api_key: str, id_or_ip: str) -> dict:
    """
    Retrieve detailed information about an X-Series instance.

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

    Returns:
        dict: The JSON response containing instance and host node details.

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

    response = requests.get(
        API_URL,
        headers=headers,
        params={"id_or_ip": id_or_ip},
        timeout=30,
    )

    try:
        data = response.json()
    except requests.exceptions.JSONDecodeError as exc:
        response.raise_for_status()
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc

    if not response.ok:
        message = data.get(
            "message",
            "The request could not be completed.",
        )

        raise RuntimeError(
            f"API request failed (HTTP {response.status_code}): "
            f"{message}"
        )

    if data.get("status") == "error":
        raise RuntimeError(
            data.get("message", "The API reported an error.")
        )

    return data


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_xseries_instance(
            api_key=api_key,
            id_or_ip="1373",
        )

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

        data = result.get("data", {})
        instance = data.get("instance_details", {})
        host = data.get("host_node_details", {})

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

        print("\nHost Node Details")
        print("Node ID:", host.get("node_id"))
        print("Node Type:", host.get("node_type"))
        print("Provider:", host.get("provider"))

    except requests.exceptions.RequestException as exc:
        print(f"HTTP or network error: {exc}.")

    except (RuntimeError, ValueError) as exc:
        print(f"API error: {exc}.")

Set your API key before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python instance_info.py

Windows PowerShell

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

To look up an VM by IP address instead, replace "1373" with required IP address in the id_or_ip argument.

Example json Response

A successful request returns a JSON object containing the request status and two main sections: instance_details and host_node_details.

HTTP Status: 200 OK

{
  "data": {
    "host_node_details": {
      "is_VM": true,
      "launch_date": "2026-01-26 11:24:02.344611",
      "node_id": 294683290,
      "node_type": "VM_RTX-A6000x2_116.0RAM_60CPU_300SSD",
      "provider": "Dataoorts_and_Lambda",
      "total_node_storage": 297
    },
    "instance_details": {
      "hourly_cost": 0.9109,
      "instance_id": 1373,
      "instance_name_id": "bjfycOc",
      "last_billed_time": "Mon, 26 Jan 2026 11:30:18 GMT",
      "name": "VM_RTX-A6000x2_116.0RAM_60CPU_300SSD",
      "os_image": "Ubuntu Server 22.04 LTS (Jammy Jellyfish)",
      "public_ip": "38.128.233.51",
      "ssh_port": 22,
      "status": "running",
      "storage_volume_gb": 297
    }
  },
  "status": "success"
}

The values above illustrate the response format. Actual instance details depend on the instance being queried and its current state.

API Response Structure

The response contains three primary fields:

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`.
`data.instance_details`	Object	Contains the VMs identity, status, operating system, IP address, SSH port, pricing, storage, and billing information.
`data.host_node_details`	Object	Contains information about the host node associated with the instance.

Instance Details

The instance_details object contains information about the individual virtual machine.

Field	Type	Description
`instance_id`	Integer	The instance's unique numeric identifier.
`instance_name_id`	String	The instance name identifier returned by the API.
`name`	String	The name or configuration identifier of the virtual machine.
`status`	String	The current instance state reported by the API, such as `running` in the example.
`public_ip`	String	The public IP address associated with the instance.
`ssh_port`	Integer	The SSH port associated with the instance.
`os_image`	String	The operating system image used by the instance.
`hourly_cost`	Number	The hourly instance cost reported by the API.
`storage_volume_gb`	Number	The instance's storage volume capacity in GB.
`last_billed_time`	String	The most recent billing timestamp reported by the API.

Host Node Details

The host_node_details object provides info about the infrastructure node associated with the instance.

Field	Type	Description
`is_VM`	Boolean	Indicates whether the associated resource is identified as a virtual machine instance.
`launch_date`	String	The launch date and time reported for the host node.
`node_id`	Integer	The identifier of the associated host node.
`node_type`	String	The host node's configuration identifier, which may include GPU, RAM, CPU, and NVMe storage details.
`provider`	String	The infrastructure provider identifier returned by the API.
`total_node_storage`	Number	Total storage value reported for the associated host node.

Usage Notes

Instance ID or IP address: Use the id_or_ip query parameter to identify the target instance. Ensure the supplied value is correct and refers to the intended virtual machine.

Instance status: The status field provides the state reported at the time of the request. The value may change as the instance moves between lifecycle states.

Pricing and billing: Use hourly_cost and last_billed_time to display the cost and billing information returned by the API. These fields represent the values reported by the endpoint and should not be treated as a guaranteed final invoice.

SSH connectivity: The public_ip and ssh_port fields can help identify connection details for the instance. Actual connectivity also depends on SSH credentials, firewall rules, and applicable network access settings.

Error Handling

If request fails, API may return unsuccessful HTTP status code & JSON response containing an error message.

Your application should handle authentication failures, invalid instance identifiers, network errors, and unexpected response formats. Do not assume that an error response contains the same data structure as a successful response.

The Python example checks the HTTP status and attempts to report the API's error message rather than treating every response as a successful instance lookup.

Get Help and Support

For assistance with instance information or API integration, contact the Dataoorts support team at [email protected].