Get All Instance Info

This endpoint retrieves a list of all K-Series workstation-based GPU instances associated with your authenticated account, alongside an aggregate breakdown of instance counts by status (active, pending, terminated, total).

Get All Instance Info - Overview

The K-Series Instances API allows authenticated users to retrieve all K-Series virtual machines associated with their Dataoorts account, along with a summary of instance counts by status.

The endpoint returns individual instance records containing the local instance ID, provider VID, GPU model, current status, connection information, hourly cost, launch time, and hardware specifications. It also provides summary counts for active, pending, terminated, and total instances.

Use this endpoint to monitor K-Series infrastructure, review GPU configurations, track instance statuses, and integrate instance information into custom dashboards or infrastructure management workflows.

Endpoint

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

HTTP

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 K-Series instance records associated with your account:

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/kseries/instances" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Replace YOUR_API_KEY with your actual Unify API key.

Python Example Implementation

The following example uses the requests library to retrieve all K-Series instances and display their summary counts, instance details, connection information, hourly costs, and hardware specifications.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def list_kseries_instances(api_key: str) -> dict | None:
    """
    Retrieve all K-Series instances and summary counts.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        The JSON response containing instance records and counts,
        or None if the API returns a non-JSON response.

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

    response = requests.get(
        API_URL,
        headers=headers,
        timeout=60,
    )

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_kseries_instances(api_key)

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

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

            print("\nInstance Summary")
            print("Active:", counts.get("active", 0))
            print("Pending:", counts.get("pending", 0))
            print("Terminated:", counts.get("terminated", 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("Provider VID:", instance.get("provider_vid"))
                print("GPU Model:", instance.get("gpu_model"))
                print("Status:", instance.get("status"))
                print("Hourly Cost:", instance.get("hourly_cost"))
                print("Launch Time:", instance.get("launch_time"))

                # Avoid printing connection credentials to logs.
                connection = instance.get("connection")
                print(
                    "Connection Available:",
                    connection not in (None, "N/A", ""),
                )

                print("RAM (GB):", specs.get("ram_gb"))
                print("Storage (GB):", specs.get("storage_gb"))
                print("vCPUs:", specs.get("vcpus"))
                print("VRAM (GB):", specs.get("vram_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 in your Env before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python kseries_instances.py

Windows PowerShell

PowerShell

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

The script displays the instance counts first, followed by each instance's identifiers, GPU model, status, hourly cost, launch time, connection availability, & hardware specifications. Avoids printing SSH credentials to console.

Example Success Response

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

HTTP Status: 200 OK

JSON

{
  "counts": {
    "active": 2,
    "pending": 0,
    "terminated": 3,
    "total": 5
  },
  "data": [
    {
      "connection": "ssh riftuser@<PUBLIC_IP> -p <SSH_PORT> | Password: <REDACTED>",
      "gpu_model": "2x RTX PRO 6000 Max-Q",
      "hourly_cost": 3.41,
      "instance_id": 56,
      "launch_time": "Thu, 25 Jun 2026 15:41:53 GMT",
      "provider_vid": "63650cca-70ac-11f1-90f9-1bad741435dd",
      "specs": {
        "ram_gb": 112,
        "storage_gb": 1700,
        "vcpus": 22,
        "vram_gb": 192
      },
      "status": "Active"
    },
    {
      "connection": "ssh riftuser@<PUBLIC_IP> -p <SSH_PORT> | Password: <REDACTED>",
      "gpu_model": "1x RTX PRO 6000 Max-Q",
      "hourly_cost": 1.705,
      "instance_id": 55,
      "launch_time": "Thu, 25 Jun 2026 15:30:00 GMT",
      "provider_vid": "ba971abc-70aa-11f1-9b27-4fa584771ed5",
      "specs": {
        "ram_gb": 56,
        "storage_gb": 850,
        "vcpus": 11,
        "vram_gb": 96
      },
      "status": "Active"
    },
    {
      "connection": "N/A",
      "gpu_model": "1x V100 SXM3",
      "hourly_cost": 0.306,
      "instance_id": 52,
      "launch_time": "Tue, 23 Jun 2026 14:53:53 GMT",
      "provider_vid": "5a1ddb00-6f13-11f1-a484-33de5bb390b3",
      "specs": {
        "ram_gb": 85,
        "storage_gb": 800,
        "vcpus": 4,
        "vram_gb": 32
      },
      "status": "terminated"
    },
    {
      "connection": "N/A",
      "gpu_model": "1x RTX 4090",
      "hourly_cost": 0.526,
      "instance_id": 51,
      "launch_time": "Tue, 23 Jun 2026 14:53:27 GMT",
      "provider_vid": "4a5f414a-6f13-11f1-a484-bf55307c45f4",
      "specs": {
        "ram_gb": 80,
        "storage_gb": 400,
        "vcpus": 15,
        "vram_gb": 24
      },
      "status": "terminated"
    },
    {
      "connection": "N/A",
      "gpu_model": "1x RTX PRO 6000 Max-Q",
      "hourly_cost": 1.705,
      "instance_id": 50,
      "launch_time": "Tue, 23 Jun 2026 14:52:58 GMT",
      "provider_vid": "3976b5fc-6f13-11f1-aea4-c356de22cfae",
      "specs": {
        "ram_gb": 56,
        "storage_gb": 850,
        "vcpus": 11,
        "vram_gb": 96
      },
      "status": "terminated"
    }
  ],
  "message": "K-Series instances list retrieved successfully.",
  "status": "success"
}

The SSH credentials and connection-specific values above have been redacted for security. The values otherwise illustrate the response structure. Instance counts, identifiers, configurations, connection details, and hourly costs may differ in subsequent API responses.

The data array may contain zero or more instances depending on your account.

Response Fields

Top-Level Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success; an unsuccessful response may return error.
message	String	A descriptive message about the result of the request.
counts	Object	Contains summary counts of instances by status.
data	Array of objects	Contains individual K-Series instance records returned by the API.

Instance Counts

The counts object provides an overview of instance states.

Field	Type	Description
counts.total	Integer	Total number of K-Series instances reported.
counts.active	Integer	Number of active instances.
counts.pending	Integer	Number of pending or provisioning instances.
counts.terminated	Integer	Number of terminated instances.

Instance Record Fields

Each object in the data array represents a K-Series instance record.

Field	Type	Description
instance_id	Integer	The local instance ID.
provider_vid	String	The provider's instance identifier (VID).
gpu_model	String	The GPU model and configuration associated with the instance.
status	String	Current VM status returned by API, such as Active or terminated.
connection	String	Connection info returned by API. Example contains SSH connection commands for active instances and N/A for terminated instances.
hourly_cost	Float	The hourly instance cost in USD.
launch_time	String	The instance launch timestamp.
specs	Object	Contains the hardware specifications associated with the instance.

Connection field clarification: The supplied response shows connection as an SSH command that may contain a password, while the original field description calls it a public IPv4 address. The table above follows the returned example format. Confirm the intended API schema before publishing the final reference.

Hardware Specification Fields

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

Field	Type	Description
specs.vcpus	Integer	Number of virtual CPUs reported for the instance.
specs.ram_gb	Integer	RAM capacity in GB.
specs.vram_gb	Integer	GPU VRAM capacity in GB.
specs.storage_gb	Integer	NVMe Storage capacity in GB.

Understanding Instance Information

Instance Status

The status field indicates the state reported for each instance. The example response includes Active and terminated instances, while the summary also provides a pending count.

Pending and provisioning instances are grouped together under counts.pending.

Use the returned status to categorize instances in your application. The counts object provides the summary, while individual records contain their own status values.

Connection Information

The connection field contains the connection information returned by the API.

In the example response, active instances return SSH commands containing a username, address, port, and password. Terminated instances return N/A.

Treat connection values as sensitive when they contain credentials. Avoid printing them to logs or exposing them in public dashboards.

Instance Ordering

The supplied documentation states that instances are returned from newest to oldest, with the most recently launched instances appearing first.

Hardware Specifications

The specs object provides the RAM, storage, vCPU, and GPU VRAM values reported for each instance.

Use these fields when displaying hardware details or comparing instance configurations.

Hourly Cost

The hourly_cost field reports the hourly cost associated with an instance. All hourly pricing values are returned in USD. The example response includes hourly costs such as 3.41, 1.705, and 0.306.

Important Notes

1. Authenticated User: This endpoint returns K-Series instances belonging to the authenticated user.

2. Instance Ordering: VMs are returned from newest to oldest according to the supplied endpoint description.

3. Instance Status: The response may include active, pending, and terminated instances. Do not assume every returned instance is currently running.

4. Status Counts: The counts object provides summary values for active, pending, terminated, and total instances. Pending and provisioning instances are grouped under pending.

5. Connection Availability: The connection field may return an SSH command or N/A. Check the value before attempting to connect.

6. Connection Security: SSH commands may contain passwords. Treat this field as sensitive and do not expose credentials in public logs, dashboards, or client-side applications.

7. Pricing Currency: All hourly pricing values are returned in USD.

8. Empty Results: If the user has no instances, the data array will be empty and all count values will be 0.

9. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

API may return unsuccessful HTTP status code & JSON error response when a request cannot be completed.

Your application should handle authentication failures, network errors, request timeouts, server errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type & handles JSON decoding errors before processing VM record.

Missing API Key

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Include the Authorization header with a valid Bearer token.

Invalid API Key

HTTP Status: 403 Forbidden

JSON

{
  "status": "error",
  "message": "Unauthorized: Invalid API key."
}

Verify that your Dataoorts API key is valid and included in the request header.

Internal Server Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Internal Server Error, Please Contact Support."
}

If the error persists, contact the Dataoorts support team for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include the Authorization header with a valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
HTTP request fails	Catch requests.exceptions.RequestException & inspect the error details.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.
No instances are returned	Check counts and data; an empty array and zero counts indicate no instances are associated with the account.
Connection is N/A	Check the instance status before attempting to connect.

Get Help and Support

For assistance with K-Series instance info or API integration, Contact support team at [email protected].