Terminate an Instance

This endpoint permanently terminates a Z-Series GPU virtual machine and deallocates its underlying compute and storage resources using either your internal Local Instance ID or the DC Provider VID.

Terminate an Instance - Overview

The Z-Series Terminate Instance API allows authenticated users to permanently terminate an existing Z-Series GPU virtual machine associated with their Dataoorts account.

The endpoint supports identifying a virtual machine using either its local Instance ID or DC Provider VID. The instance_id parameter can be supplied in the JSON request body or as a URL query parameter.

Before termination, the API automatically calculates and settles any outstanding usage charges. After successful termination, the VM's stored SSH information is removed and replaced with N/A.

Warning: This operation is permanent and cannot be undone. Once terminated, the virtual machine and its associated resources cannot be recovered.

Endpoint

Property	Value
HTTP Method	DELETE or POST
Endpoint	/zseries/delete
Full URL	https://cloud.dataoorts.com/api/v1/zseries/delete
Authentication	Bearer Token
Request Format	JSON body or URL query parameter
Response Format	JSON

The endpoint accepts DELETE requests and also supports POST requests for clients that do not support the HTTP DELETE method.

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
Content-Type: application/json
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 instance_id parameter to identify the Z-Series virtual machine to terminate.

Parameter	Type	Required	Description
instance_id	String or Integer	Yes	The local Instance ID or DC Provider VID of the virtual machine to terminate.

The parameter can be supplied in either the JSON request body or the URL query string.

Example Request Body — Local Instance ID

JSON

{
  "instance_id": 20
}

Example Request Body — DC Provider VID

JSON

{
  "instance_id": "659683"
}

Replace the example value with Local Instance ID or DC Provider VID of the VM you want to terminate.

Request Examples

cURL - Use the following command to terminate VM using its local Instance ID in the JSON request body:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/zseries/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 20
  }'

To terminate a virtual machine using its DC Provider VID, Provide that identifier as the instance_id value:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/zseries/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": "659683"
  }'

Alternative Request Using a Query Parameter

The API also accepts the instance identifier as a URL query parameter.

Using a Local Instance ID:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/zseries/delete?instance_id=20" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Using a DC Provider VID:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/zseries/delete?instance_id=659683" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Alternative POST Request

Clients that do not support HTTP DELETE method, use POST with the same endpoint and JSON request body:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/zseries/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 20
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key and provide the identifier of the intended virtual machine Instance.

Python Example Implementation

The following example uses the requests library to terminate a 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/delete"


def delete_zseries_instance(
    api_key: str,
    instance_id: int | str,
) -> dict | None:
    """
    Permanently terminate a Z-Series GPU virtual machine.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The local Instance ID or Provider VID.

    Returns:
        The JSON response containing the termination result,
        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}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "instance_id": instance_id,
    }

    response = requests.delete(
        API_URL,
        headers=headers,
        json=payload,
        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."
        )

    # Replace with the local Instance ID or Provider VID.
    instance_id = 20

    try:
        result = delete_zseries_instance(
            api_key=api_key,
            instance_id=instance_id,
        )

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

            if "current_status" in result:
                print("Current Status:", result.get("current_status"))

    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 Secrets before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python zseries_delete.py

Windows PowerShell

PowerShell

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

The script submits the instance identifier and displays the returned status, message, and current instance status when provided by the API.

Example Success Response

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

JSON

{
  "current_status": "terminated",
  "message": "Instance 20 terminated successfully.",
  "status": "success"
}

The instance ID and response message may differ depending on the virtual machine being terminated.

Already Terminated VM Response

If the virtual machine has already been terminated, the API returns a successful response instead of an error.

JSON

{
  "status": "success",
  "message": "Instance is already terminated."
}

In this response, the current_status field is not included.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success; an unsuccessful response returns error.
message	String	A descriptive message about the termination result.
current_status	String	The VM status returned after termination. The successful termination example returns terminated. This field is not included in the already-terminated response.

Understanding Instance Information

Instance Identification

The instance_id parameter identifies the Z-Series virtual machine targeted by the request.

You can provide either the local Instance ID or Provider VID. The identifier can be supplied in the JSON request body or as a URL query parameter.

Instance Termination

When the API returns "status": "success" and "current_status": "terminated", the response indicates that the virtual machine has been terminated successfully.

If VM is already terminated, API returns successful response with message Instance is already terminated.

Billing and Connection Information

Before termination, the API automatically calculates and settles any outstanding usage charges.

After successful termination, the virtual machine's stored SSH information is removed and replaced with N/A.

Instance Termination Workflow

The Z-Series Instance termination process follows these steps:

1. Authenticate using your Dataoorts Unify API key.
2. Identify the virtual machine using its local Instance ID or DC Provider VID.
3. Submit a DELETE request to /api/v1/zseries/delete, or use POST if the client not support DELETE.
4. Supply the instance_id in the JSON request body or URL query parameter.
5. The API validates the request and checks access to the requested instance.
6. The system automatically calculates and settles outstanding usage charges.
7. After successful termination, the GPU VM Instance status becomes terminated and its stored SSH information is replaced with N/A.

Important Notes

1. Permanent Termination: This operation is irreversible. A terminated GPU VM Instance and its associated resources cannot be recovered.

2. Instance Identifier: Provide either Local Instance ID or DC Provider VID through instance_id parameter.

3. HTTP Methods: Both DELETE and POST methods are supported. Use DELETE as the primary method and POST when the client does not support DELETE.

4. Request Parameter: The instance_id can be supplied in JSON request body or as a URL query parameter.

5. User Access: Only instances owned by the authenticated user can be terminated.

6. Outstanding Charges: The system automatically settles outstanding usage charges before VM termination.

7. Connection Information: After termination, the stored SSH information is removed and replaced with N/A.

8. Already-Terminated VMs: If the GPU virtual machine Instance has already been terminated, the API still returns a successful response instead of an error.

9. Request Timeout: If the request times out, check the latest instance status before retrying because the outcome of the original request may be uncertain.

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

Error Handling

The API may return an unsuccessful HTTP status code and a JSON error response when a termination request cannot be completed.

Your application should handle authentication failures, missing instance identifiers, instances that cannot be found or accessed, provider API failures, db transaction errors, server errors, & unexpected response formats.

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

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 Unify API Key/Token is valid and included in the request header.

Missing Instance ID

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Missing required field: 'instance_id'."
}

Provide the required instance_id in the JSON request body or as a URL query parameter.

Instance Not Found

HTTP Status: 404 Not Found

JSON

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

Verify that the instance identifier is correct and that the VM belongs to the authenticated user.

DC Provider API Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "API Failed to Delete Instance, Please Contact Support."
}

This response indicates DC Provider API failure. Contact our team at [email protected] if the issue persists.

Database Transaction Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Database transaction error during termination, Try again later."
}

This response indicates an error during the database transaction associated with termination. Check the Z Series GPU Instance live status before retrying the termination request.

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	IncludeAuthorization header with a valid Bearer token.
API token is empty	Set a non-empty DATAOORTS_API_KEY env variable.
API key is invalid	Verify the API key through the Dataoorts platform.
Instance ID is missing	Provide instance_id in the request body or query string.
Instance is not found or access is denied	Verify the identifier and confirm that the VM belongs to the authenticated user.
Provider API returns 502	Contact support "[email protected]" if error persists.
Database transaction fails	Check the current GPU Instance status before retrying.
Request times out	Verify the GPU VM Instance status before submitting another termination request.
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.

Get Help and Support

For assistance with Z-Series VM Termination or API Integration, Contact support team at [email protected].