Terminate an Instance

This endpoint permanently terminates a specific X-Series GPU virtual machine instance and deletes all associated data.

Terminate an Instance - Overview

The X-Series Instance Termination API allows authenticated users to permanently terminate a specific virtual machine using its Instance ID or IP address.

Terminating an instance permanently removes the instance and deletes its associated data. Once the termination is completed, the deleted data cannot be recovered using the instance ID or IP address.

This endpoint is intended for instances that are no longer needed. It can be integrated into infrastructure automation workflows, resource cleanup scripts, and custom instance management applications.

Warning: This action is irreversible. Terminating an instance permanently deletes its data. Verify the target instance and ensure that any required data has been backed up before submitting the request.

Endpoint

Property	Value
HTTP Methods	POST or DELETE
Endpoint	/xseries/delete
Full URL	https://cloud.dataoorts.com/api/v1/xseries/delete
Authentication	Bearer Token
Content Type	application/json
Response Format	JSON

Both POST and DELETE are supported by provided integration. Examples below demonstrate each option.

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 request body must be sent as JSON.

Parameter	Type	Required	Description
id_or_ip	String	Yes	The Instance ID or IP address of the virtual machine you want to terminate.

Provide the identifier of the intended instance, Carefully verify the value before submitting the request because the operation permanently deletes the instance and its data.

Request Examples

cURL with POST - Use the following command to terminate an instance using its Instance ID:

Bash

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

cURL with DELETE - Alternatively, you can use the DELETE HTTP method:

Bash

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

Replace YOUR_API_KEY and the example instance identifier with your actual values.

You can also supply an IP address as id_or_ip value. Use identifier of the instance you intend to terminate.

Python Example Implementation:

Python

import os
import requests


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


def terminate_xseries_instance(
    api_key: str,
    id_or_ip: str,
    method: str = "POST",
) -> dict:
    """
    Permanently terminate an X-Series instance.

    WARNING:
        This operation deletes the instance and its associated data.
        Deleted data cannot be recovered using the instance ID or IP.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_ip: The instance ID or IP address.
        method: HTTP method, either POST or DELETE.

    Returns:
        dict: The JSON response returned by the API.

    Raises:
        ValueError: If the HTTP method or JSON response is invalid.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    method = method.upper()

    if method not in {"POST", "DELETE"}:
        raise ValueError("method must be 'POST' or 'DELETE'.")

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "id_or_ip": id_or_ip,
    }

    response = requests.request(
        method=method,
        url=API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

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

    # Verify the instance identifier before running this operation.
    instance_id = "1373"

    # This operation permanently deletes the selected instance.
    try:
        result = terminate_xseries_instance(
            api_key=api_key,
            id_or_ip=instance_id,
            method="POST",
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))
        print("Rebate Credited:", result.get("rebate_credited"))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid request or response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python terminate_instance.py

Windows PowerShell

PowerShell

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

To use the DELETE method, change method="POST" to method="DELETE" in the function call.

Important: The Python example performs the termination request directly. Confirm the instance identifier and backup requirements before running it.

Example Success Response

When an instance is terminated successfully, the API returns a JSON response similar to the following:

JSON

{
  "message": "Instance 1373 terminated successfully.",
  "rebate_credited": true,
  "status": "success"
}

The instance identifier and returned values depend on the actual operation.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	Provides a message confirming the termination result.
rebate_credited	Boolean	Indicates whether a rebate was credited, as reported by the API.

The rebate_credited field reports the result provided by the API. Refer to the applicable Dataoorts billing terms for rebate eligibility and calculation details.

What Happens After Termination?

After a successful termination:

1. The API reports the termination result.
2. The instance and its associated data are permanently deleted.
3. The deleted instance data cannot be recovered using its Instance ID or IP address.
4. Any applicable rebate information is reported through the rebate_credited field.

A successful response should be interpreted according to the result reported by the API - If the request times out or returns an error, do not automatically assume that the termination did not occur.

Important Notes

Permanent Data Loss

Termination is irreversible. Back up any required files, datasets, configurations, and application data before submitting the request.

Verify the Target Instance

Ensure that id_or_ip identifies the correct instance. In automated workflows, validate the target instance and consider adding an explicit confirmation step before executing this operation.

Handle Network Errors Carefully

A timeout does not necessarily mean that the server failed to process the request. Before retrying a failed termination request, check the instance state using the appropriate instance information endpoint.

Rebate Information

The API may include rebate_credited in the response. Do not assume a rebate is guaranteed for every termination; refer to the response and the applicable billing rules.

Error Handling

If request fails, API may return unsuccessful HTTP status code & JSON response containing an error message.

Your application should handle authentication failures, invalid instance identifiers, network errors, timeouts, and unexpected response formats. The exact error codes and response messages depend on the API response.

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

Get the Support

For assistance with instance termination, billing-related questions, or API integration, contact the Dataoorts support team at [email protected].