Single Instance Info

This endpoint retrieves complete configuration details, real-time operational status, hardware specifications, hourly pricing, and ready-to-use secure SSH connection credentials for a single Z-Series enterprise GPU virtual machine.

Single Instance Info - Overview

The Z-Series Single Instance API allows authenticated users to retrieve detailed information about a single Z-Series GPU virtual machine associated with their Dataoorts account.

The endpoint supports searching by either the local instance ID or the provider VID. The response includes the instance ID, provider VID, GPU model, current status, SSH command, hourly GPU cost, hardware specifications, launch time, and next billing cycle.

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

Endpoint

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

Parameter	Type	Required	Description
id_or_vid	String	Yes	The local instance ID or DC Provider VID of the virtual machine whose information you want to retrieve.

Example Request

HTTP

GET /api/v1/zseries/instance?id_or_vid=205

You can provide either the local instance ID or the DC Provider VID as the parameter value.

Request Examples

cURL - Use the following command to retrieve information about a Z-Series VM using its local instance ID:

Bash

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

To retrieve information using the DC Provider VID, provide that identifier as the id_or_vid query parameter.

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/zseries/instance?id_or_vid=434190" \
  --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 virtual machine you want to retrieve.

Python Example Implementation

The following example uses the requests library to retrieve information about a single Z-Series virtual machine. 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/zseries/instance"


def get_zseries_instance(
    api_key: str,
    id_or_vid: str,
) -> dict | None:
    """
    Retrieve detailed information about a single Z-Series VM.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_vid: The local instance ID or provider 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=180,
    )

    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_zseries_instance(
            api_key=api_key,
            id_or_vid="205",
        )

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

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

            print("\nZ-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"),
            )

            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"))

            # SSH commands contain connection details.
            # Avoid printing them to shared or public logs.
            print(
                "SSH Command Available:",
                bool(data.get("ssh_command")),
            )

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

Windows PowerShell

PowerShell

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

The script retrieves the requested virtual machine information and displays its identifiers, GPU model, status, hardware specifications, hourly cost, and billing timestamps.

Example Success Response

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

HTTP Status: 200 OK

JSON

{
  "data": {
    "gpu_model": "L4",
    "hourly_cost": 0.48,
    "instance_id": 19,
    "launch_time": "Fri, 26 Jun 2026 05:27:29 GMT",
    "next_billing_cycle": "Fri, 26 Jun 2026 05:47:29 GMT",
    "provider_vid": "434190",
    "specs": {
      "cpu_cores": 28,
      "gpu_count": 1,
      "ram_gb": 124,
      "storage_gb": 800,
      "vram_gb": 24
    },
    "ssh_command": "ssh -i temporary.pem -o StrictHostKeyChecking=no [email protected]",
    "status": "Active"
  },
  "message": "Instance info retrieved.",
  "status": "success"
}

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

Note: If the virtual machine has been terminated, the response still contains its details, but next_billing_cycle 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 Z-Series virtual machine.

Instance Record Fields

The data object contains the information returned for the requested virtual machine.

Field	Type	Description
data.instance_id	Integer	The local instance ID assigned to the VM.
data.provider_vid	String	The provider's virtual machine identifier.
data.gpu_model	String	The GPU model associated with the VM.
data.status	String	The current VM status returned by the REST API, such as Active.
data.ssh_command	String	The SSH command returned for connecting to VM.
data.hourly_cost	Float	The hourly GPU compute cost in USD. Storage is billed separately.
data.launch_time	String	The virtual machine launch timestamp.
data.next_billing_cycle	String or Null	The next billing timestamp. Returns null if the virtual machine has been terminated.
data.specs	Object	Contains the hardware specifications associated with the virtual machine.

Hardware Specification Fields

The specs object contains the hardware configuration reported for the virtual machine.

Field	Type	Description
data.specs.gpu_count	Integer	Number of GPUs allocated to the virtual machine.
data.specs.cpu_cores	Integer	Total number of vCPU cores reported for the VM.
data.specs.ram_gb	Integer	Total RAM capacity in GB.
data.specs.vram_gb	Integer	Total GPU VRAM capacity in GB.
data.specs.storage_gb	Integer	Allocated NVMe storage capacity in GB.

Understanding Instance Information

Instance Identification

Use the id_or_vid query parameter to identify the Z-Series virtual machine 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 virtual machine using either identifier.

Instance Status

The status field indicates the current virtual machine status returned by the API. The example response returns Active.

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

SSH Connection

The ssh_command field provides the SSH command returned by the API. The example uses the temporary.pem private key to connect to the virtual machine.

Use the downloaded private key as required by the command and keep it secure. Avoid publishing SSH connection details in shared logs, dashboards, or client-side applications.

Hardware Specifications

The specs object provides the GPU count, CPU cores, RAM, VRAM, and NVMe storage capacity associated with the virtual machine.

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 GPU compute cost in USD. Storage is billed separately.

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

If the virtual machine 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 Data Center (DC) Provider VID through the id_or_vid query parameter.

2. User Access: Only instances belonging to the authenticated user can be accessed. Requests for instances belonging to other users return 404 Not Found.

3. SSH Connection: The returned ssh_command can be used with the downloaded temporary.pem private key. Keep the private key and connection information secure.

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

5. Separate Storage Billing: The hourly_cost field represents the hourly GPU VM compute cost. NVMe Storage is billed separately.

6. Terminated Instances: The response can still contain information about a terminated virtual machine. Its next_billing_cycle field will be null.

7. Current State: Instance details reflect the information returned at the time of the request. Retrieve the latest information when status, connection availability, 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

API may return unsuccessful HTTP status code & JSON error response when a 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.

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

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.

Missing Token

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "API Token is missing or empty."
}

Ensure that the API token is present and non-empty.

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 the request URL.

Instance Not Found

HTTP Status: 404 Not Found

JSON

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

Verify that the Instance ID or DC Provider VID is correct and that the VM 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 at [email protected] for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include Authorization header with a valid Bearer Token.
API token is empty	Set a non-empty UNIFY_API_KEY environment variable.
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 that the virtual machine 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 virtual machines.

Get Help and Support

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