Single Instance Info

Get Single Instance Info - Overview

The Nova Series Instance Info API allows authenticated users to retrieve detailed information and the current status of a specific Nova virtual machine using its instance ID or IP address.

The endpoint returns instance details, including the GPU configuration, instance status, pricing contract, hourly cost, public IP address, operating system image, region, SSH username, and billing timestamps. It also provides hardware specifications such as GPU count, CPU cores, RAM, VRAM, and storage capacity.

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

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/nova/instance`
Full URL	`https://cloud.dataoorts.com/api/v1/nova/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 or IP address of the Nova virtual machine whose information you want to retrieve.

Provide the identifier of the intended instance, Ensure that the instance belongs to your account and that the supplied ID or IP address is correct.

Request Examples

1. Get Instance Information Using Instance ID

cURL - Retrieve details for an instance using its ID:

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

2. Get Instance Information Using IP Address

You can also identify the instance using its public IP address.

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

Replace YOUR_API_KEY and the example instance identifier with your actual values.

Python Example Implementation

import os
import json
import requests


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


def get_nova_instance(
    api_key: str,
    id_or_ip: str,
) -> dict:
    """
    Retrieve detailed information about a Nova 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 details.

    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=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 = get_nova_instance(
            api_key=api_key,
            id_or_ip="430",
        )

        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("Name:", instance.get("name"))
        print("Status:", instance.get("status"))
        print("Public IP:", instance.get("public_ip"))
        print("Region:", instance.get("region"))
        print("Contract:", instance.get("contract"))
        print("Hourly Cost:", instance.get("hourly_cost"))

        print("\nHardware Specifications")
        print("GPU Model:", instance.get("name"))
        print("GPU Count:", specs.get("gpu_count"))
        print("CPU Cores:", specs.get("cpu_cores"))
        print("RAM (GB):", specs.get("ram_gb"))
        print("VRAM (GB):", specs.get("vram_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 nova_instance_info.py

Windows PowerShell

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

To retrieve info using an IP address instead, replace "430" in the function call with the appropriate IP address.

Example Success Response

A successful request returns a JSON object containing the instance information under `data`, along with the overall response status.

HTTP Status: 200 OK

{
  "data": {
    "contract": "on-demand",
    "hourly_cost": 2.6335,
    "instance_id": 430,
    "last_billed_time": "Wed, 28 Jan 2026 04:21:37 GMT",
    "launch_time": "Wed, 28 Jan 2026 02:48:22 GMT",
    "name": "1x H100 SXM5 80GB",
    "os_image_id": "ubuntu-24.04-cuda-12.8-open-docker",
    "os_volume_id": "9de33a45-2642-42f1-980d-d59d9e65ec02",
    "provider_vmid": "336b1c8a-d04b-49f2-831d-9e2e458984a1",
    "public_ip": "95.133.252.78",
    "region": "FIN-03",
    "specs": {
      "cpu_cores": 32,
      "gpu_count": 1,
      "ram_gb": 185,
      "storage_gb": 150,
      "vram_gb": 80
    },
    "ssh_user": "root",
    "status": "running"
  },
  "status": "success"
}

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

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`.
`data`	Object	Contains the details of the requested Nova instance.
`data.instance_id`	Integer	The identifier assigned to the instance.
`data.name`	String	The display name or GPU configuration name of the instance.
`data.status`	String	The current instance status reported by the API, such as `running` in the example response.
`data.contract`	String	The pricing contract associated with the instance, such as `on-demand`.
`data.hourly_cost`	Float	The hourly cost reported for the instance.
`data.public_ip`	String	The public IP address associated with the instance.
`data.region`	String	The region in which the instance is deployed.
`data.ssh_user`	String	The SSH username associated with the instance.
`data.os_image_id`	String	The operating system image identifier associated with the instance.
`data.os_volume_id`	String	The identifier of the operating system volume associated with the instance.
`data.provider_vmid`	String	The virtual machine identifier returned by the underlying provider.
`data.launch_time`	String	The launch timestamp reported for the instance.
`data.last_billed_time`	String	The most recent billing timestamp reported by the API.
`data.specs`	Object	Contains the hardware specifications of the instance.

Hardware Specifications

The data.specs object provides details about the instance's allocated hardware resources.

Field	Type	Description
`specs.gpu_count`	Integer	The number of GPUs allocated to the instance.
`specs.cpu_cores`	Integer	The number of CPU cores reported for the instance.
`specs.ram_gb`	Number	The RAM capacity in GB.
`specs.vram_gb`	Number	The total GPU video memory capacity in GB.
`specs.storage_gb`	Number	The storage capacity in GB reported for the instance.

Understanding Instance Information

1. Instance Status

The status field indicates the instance state reported by the API. Use it to display the current state in your application or to determine when a follow-up action may be appropriate.

The example response reports running. Other status values should be interpreted according to the actual values returned by the API.

2. Pricing Contract

The contract field identifies the pricing contract associated with the instance, such as on-demand. Use this field together with hourly_cost when displaying instance pricing information.

3. Operating System and Storage

The os_image_id field identifies the OS image associated with the instance, while os_volume_id identifies its associated operating system volume.

These identifiers can be useful when integrating instance information with other Nova storage or provisioning workflows.

4. Billing Timestamps

The launch_time and last_billed_time fields provide timestamps reported by the API for the instance's launch and most recent billing activity.

Use the values as returned by the endpoint when displaying instance history or billing-related information.

Important Notes

1. Correct Instance Identifier: Provide the correct instance ID or IP address through the id_or_ip query parameter.

2. Status May Change: The returned status reflects the information available at the time of the request. Retrieve the latest instance information when current state is important.

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

4. SSH Connectivity: The public_ip and ssh_user fields can help identify the connection details. Actual connectivity also depends on valid SSH credentials, network configuration, and access rules.

5. Provider Identifier: The provider_vmid field is the provider-side identifier returned by the API. Use it only where a workflow explicitly requires that identifier.

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, 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 Nova instance information, configuration details, or API integration, contact the Dataoorts support team at [email protected].