Get All Instances Info

Get All Instances Info - Overview

The X-Series Instances API allows authenticated users to retrieve information about their X-Series virtual machine instances through a single API request.

The endpoint returns a list of instance records along with summary counts for different instance states, including running, stopped, and terminated instances. Each record may include the instance ID, configuration name, current status, public IP address, hourly cost, category, and active duration.

Use this endpoint to build custom infrastructure dashboards, monitor instance states, review historical instance records, and integrate instance information into automated management workflows.

The response reflects the records and state information returned by the API at the time of the request.

Endpoint

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

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/xseries/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:

import os
import requests


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


def list_xseries_instances(api_key: str) -> dict:
    """
    Retrieve X-Series 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 server returns an invalid JSON response.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
    }

    response = requests.get(
        API_URL,
        headers=headers,
        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 = list_xseries_instances(api_key)

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

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

        print("\nInstance Summary")
        print("Running:", counts.get("running", 0))
        print("Stopped:", counts.get("stopped", 0))
        print("Terminated:", counts.get("terminated", 0))
        print("Total:", counts.get("total", 0))

        print("\nInstance Records")

        for instance in result.get("data", []):
            print("-" * 40)
            print("Instance ID:", instance.get("instance_id"))
            print("Name:", instance.get("name"))
            print("Status:", instance.get("status"))
            print("Category:", instance.get("category"))
            print("Public IP:", instance.get("public_ip"))
            print("Hourly Cost:", instance.get("hourly_cost"))
            print(
                "Active Duration (hours):",
                instance.get("active_duration_hours"),
            )

    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 xseries_instances.py

Windows PowerShell

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

The script prints the instance status summary first, followed by the details of each returned record.

Example Response

A successful request returns a JSON object containing status counts and an array of instance records.

HTTP Status: 200 OK

{
  "counts": {
    "running": 0,
    "stopped": 0,
    "terminated": 20,
    "total": 20
  },
  "data": [
    {
      "active_duration_hours": 0.4220268003,
      "category": "history",
      "hourly_cost": "N/A",
      "instance_id": 1387,
      "name": "VM_H100x1_180.0RAM_28CPU_850SSD",
      "public_ip": "N/A",
      "status": "terminated"
    },
    {
      "active_duration_hours": 0.3589659456,
      "category": "history",
      "hourly_cost": "N/A",
      "instance_id": 1373,
      "name": "VM_RTX-A6000x2_116.0RAM_60CPU_300SSD",
      "public_ip": "N/A",
      "status": "terminated"
    }
  ],
  "status": "success"
}

The response above is an abbreviated illustration of the response structure. The counts and instance records returned by the live API may differ; the actual response can contain more records.

Response Structure

The response contains three top-level fields:

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`.
`counts`	Object	Provides summary counts for instance states and the total number of records reported.
`data`	Array of objects	Contains the instance records returned by the endpoint.

Instance Counts

The counts object summarizes the instance states reported by the API.

Field	Type	Description
`running`	Integer	Number of instances reported as running.
`stopped`	Integer	Number of instances reported as stopped.
`terminated`	Integer	Number of instances reported as terminated.
`total`	Integer	Total number of records reported in the summary.

These counts help you display an at-a-glance overview of your X-Series infrastructure.

Instance Record Fields

Each object in the data array represents an instance record.

Field	Type	Description
`instance_id`	Integer	The identifier associated with the instance record.
`name`	String	The instance name or configuration identifier. It may include pricing text in the returned value.
`status`	String	The instance state reported by the API, such as `running`, `stopped`, or `terminated`.
`category`	String	The record category returned by the API. The example response includes `history`.
`public_ip`	String	The public IP address associated with the record. May contain `N/A` when an IP address is not available or applicable.
`hourly_cost`	String or Float	The hourly cost reported for the record. The example uses `N/A` for terminated records.
`active_duration_hours`	Float	The active duration associated with the record, expressed in hours.

Note: The hourly_cost field may be returned as either a number or a string such as N/A. Applications should handle both types rather than assuming every value is numeric.

Understanding Instance Records

Active and Terminated Instances

The status field indicates the state reported for an instance record. You can use it to categorize records in a dashboard or filter the returned data in your application.

For example, application can identify records with status equal to running to display currently running VMs.

Historical Records

The API response may include records with category set to history, as shown in the example. These records provide historical instance information, including the reported status and active duration.

The same instance_id may appear in multiple returned records. Therefore, do not assume that every object in the data array represents a unique instance ID.

Public IP and Hourly Cost

Some records may contain N/A for public_ip or hourly_cost. Your application should handle these values gracefully instead of treating them as valid IP addresses or numeric prices.

Active Duration

The active_duration_hours field reports the active duration in hours. You can use it to display runtime-related information in your application.

Usage Examples

This endpoint can be used to:

Display instance status counts in an infrastructure dashboard.
Retrieve the instance records available to the authenticated account.
Separate running, stopped, and terminated records in an application.
Review historical records and their reported active durations.
Build reporting and monitoring workflows around instance information.

Error Handling

If request fails, the API may return an unsuccessful HTTP status code instead of the expected success response.

Common causes include authentication failures, network errors, request timeouts, and server errors.

In Python, response.raise_for_status() raises an exception when the server returns an unsuccessful HTTP status code. Handle these exceptions to avoid interrupting your application's workflow.

Do not assume that an error response contains the same fields as a successful response.

Get the Support

For assistance with X-Series instance records or API integration, contact the Dataoorts support team at [email protected].