Single Instance Info

This endpoint retrieves detailed configuration information, live operational status, hardware specifications, hourly pricing, and secure connection credentials for a single K-Series workstation instance.

Single Instance Info - Overview

The K-Series Instance Information API allows authenticated users to retrieve detailed information about a single K-Series instance associated with their Dataoorts account.

The endpoint supports searching by either the local instance ID (id) or the provider instance ID (vid). The response includes the instance ID, provider VID, GPU model, current status, connection details, hourly cost, hardware specifications, launch time, and next billing cycle.

Use this endpoint to inspect a specific K-Series instance, review its configuration, monitor its status, and retrieve its associated billing information.

Endpoint

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

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

The endpoint requires the id_or_vid query parameter to identify the K-Series instance.

Parameter	Type	Required	Description
id_or_vid	String	Yes	The local instance ID or provider DDRA VID of the instance whose information you want to retrieve.

Example Request

HTTP

GET /api/v1/kseries/instance?id_or_vid=123

You can provide either the local instance ID or the provider instance ID (VID) as the parameter value.

Request Examples

cURL - Use the following command to retrieve info about a K-Series instance using its local instance ID:

Bash

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

To retrieve an instance using its DC provider VID, provide that identifier as the id_or_vid query parameter.

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/kseries/instance?id_or_vid=ba971abc-70aa-11f1-9b27-4fa584771ed5" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Replace YOUR_API_KEY and the example identifier with your actual API key and the identifier of the instance you want to retrieve.

Python Example Implementation

The following example uses the requests library to retrieve information about a single K-Series instance. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks the response format before processing the returned data.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def get_kseries_instance(
    api_key: str,
    id_or_vid: str,
) -> dict | None:
    """
    Retrieve detailed information about a single K-Series instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_vid: The local instance ID or provider instance VID.

    Returns:
        The JSON response containing instance information,
        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",
    }

    params = {
        "id_or_vid": id_or_vid,
    }

    response = requests.get(
        API_URL,
        headers=headers,
        params=params,
        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 = get_kseries_instance(
            api_key=api_key,
            id_or_vid="123",
        )

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

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

            print("\nK-Series Instance Details")
            print("Instance ID:", data.get("instance_id"))
            print("Provider VID:", data.get("provider_vid"))
            print("GPU Model:", data.get("gpu_model"))
            print("Status:", data.get("status"))
            print("Hourly Cost:", data.get("hourly_cost"))
            print("Launch Time:", data.get("launch_time"))
            print("Next Billing Cycle:", data.get("next_billing_cycle"))

            print("\nConnection Details")
            print("Connection:", data.get("connection"))

            specs = data.get("specs", {})
            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("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 in Env before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python kseries_instance_info.py

Windows PowerShell

PowerShell

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

The script retrieves the requested instance information and displays its identifiers, GPU model, current status, connection details, hardware specifications, hourly cost, and billing timestamps.

Example Success Response

A successful request returns a JSON object containing the requested instance details, a descriptive message, and the response status.

JSON

{
  "data": {
    "connection": "ssh <SSH_USER>@<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",
    "next_billing_cycle": "Thu, 25 Jun 2026 15:40:00 GMT",
    "provider_vid": "ba971abc-70aa-11f1-9b27-4fa584771ed5",
    "specs": {
      "cpu_cores": 11,
      "gpu_count": 1,
      "ram_gb": 56,
      "storage_gb": 850,
      "vram_gb": 96
    },
    "status": "Active"
  },
  "message": "Ins info retrieved successfully",
  "status": "success"
}

The values above illustrate the response structure. Instance identifiers, connection details, hardware specifications, status, and costs may differ in subsequent API responses.

Note: If the instance has been terminated, the next_billing_cycle field will be null.

Response 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.
data	Object	Contains the details of the requested K-Series instance.

Instance Record Fields

The data object contains the information returned for the requested instance.

Field	Type	Description
data.instance_id	Integer	The local instance ID assigned to the instance.
data.provider_vid	String	The provider's instance identifier (VID).
data.gpu_model	String	The GPU model and configuration associated with the instance.
data.status	String	The current instance status returned by the API, such as Active.
data.connection	String	Connection information returned by the API. The example contains an SSH command with a username, IP address, port, and password.
data.hourly_cost	Float	The hourly billing cost in USD.
data.launch_time	String	The instance launch timestamp.
data.next_billing_cycle	String or Null	The next billing timestamp, or null if the instance has been terminated.
data.specs	Object	Contains the hardware specifications returned for the instance.

Connection field clarification: The supplied response example shows data.connection as an SSH command with connection credentials, although the original response-field description calls it a public IPv4 address. Confirm the intended API schema before publishing the final reference. The example above follows the connection format shown in the supplied JSON.

Hardware Specification Fields

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

Field	Type	Description
data.specs.gpu_count	Integer	Number of GPUs associated with the instance.
data.specs.cpu_cores	Integer	Number of vCPU cores reported for the instance.
data.specs.ram_gb	Integer	RAM capacity in GB.
data.specs.vram_gb	Integer	GPU VRAM capacity in GB.
data.specs.storage_gb	Integer	Storage capacity in GB.

Understanding Instance Information

Instance Identification

Use the id_or_vid query parameter to identify the K-Series instance you want to retrieve.

The endpoint supports lookup by either the local instance ID or the provider VID. The response returns both instance_id and provider_vid, allowing you to identify the instance using either identifier.

Instance Status

The status field indicates the current status returned for the requested instance. The example response returns Active.

Use the returned status to represent the instance state in your application. Retrieve the latest instance information when the current state is important.

Connection Information

The connection field contains the connection information returned by the API. In the supplied example, it includes an SSH command, username, IP address, port, and password.

Treat this field as sensitive because it may contain credentials. Do not expose it in public logs, dashboards, or client-side applications.

Hardware Specifications

The specs object provides GPU count, CPU cores, RAM, VRAM, and storage capacity associated with instance.

Use these fields to display hardware details in dashboards or infrastructure management tools.

Hourly Cost and Billing Information

The hourly_cost field reports the hourly billing cost in USD. In the example response, the value is 1.705.

The launch_time field provides the instance launch timestamp, while next_billing_cycle indicates the next billing timestamp.

If the instance has been terminated, next_billing_cycle returns null. Handle this value in your application rather than assuming a billing timestamp is always available.

Important Notes

1. Instance Lookup: Provide either the local instance ID or provider VID through the id_or_vid query parameter.

2. User Access: The API only returns instances belonging to the authenticated user. Accessing another user's instance returns 404 Not Found.

3. Pricing Currency: All pricing values are returned in USD.

4. Terminated Instances: The response can still include details for a terminated instance. Its next_billing_cycle field will be null.

5. Connection Security: The connection field may contain sensitive SSH credentials. Protect this information and avoid publishing real credentials in documentation.

6. Billing Timestamps: Use launch_time and next_billing_cycle to display the returned billing-related timestamps.

7. Current State: Instance details reflect the information returned at the time of the request. Retrieve the latest information when current status or billing information is important.

8. 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

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

Your application should handle authentication failures, missing query parameters, instances that cannot be found or accessed, server errors, network errors, and unexpected response formats.

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.

Missing Query Parameter

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Please provide Instance 'id or vid' as a query parameter."
}

Include the required id_or_vid query parameter in your request.

Instance Not Found

HTTP Status: 404 Not Found

JSON

{
  "status": "error",
  "message": "K-Series Instance not found or access denied."
}

Verify that the instance ID or provider VID is correct and that the instance belongs to the authenticated user.

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 Authorization header with valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
Query parameter is missing	Provide id_or_vid in the request URL.
Instance is not found or access is denied	Verify the identifier and confirm the instance belongs to the authenticated user.
HTTP request fails	Catch requests.exceptions.RequestException and 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.
next_billing_cycle is null	Handle the missing billing timestamp, which is expected for terminated instances.

Get Help and Support

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