Restart an Instance

This endpoint resumes a previously hibernated Z-Series enterprise GPU virtual machine, restoring it to an active operational state and restarting billing.

Restart an Instance - Overview

The Z-Series Resume Instance API allows authenticated users to resume a previously hibernated Z-Series GPU virtual machine associated with their Dataoorts account.

The endpoint accepts an instance_id that identifies the virtual machine using either its local instance ID or provider VID. Before resuming, the API verifies that the virtual machine exists, belongs to the authenticated user, is currently in the Hibernated state, and that the user has sufficient account balance.

If the resume operation succeeds, the virtual machine returns to the Active state. The response includes the updated provider VID and a new SSH connection command.

Important: Only hibernated virtual machines can be resumed. The local Instance ID remains unchanged, while the Provider VID resets with every restart.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/zseries/resume
Full URL	https://cloud.dataoorts.com/api/v1/zseries/resume
Authentication	Bearer Token
Request Format	JSON
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
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 a JSON request body containing the identifier of the Z-Series virtual machine to resume.

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

Example Request Body — Local Instance ID

JSON

{
  "instance_id": 19
}

Example Request Body — DC Provider VID

JSON

{
  "instance_id": "69854"
}

Replace the example value with local Instance ID or DC Provider VID of the virtual machine you want to resume.

Request Examples

cURL - Use the following command to resume a hibernated Z-Series VM using its Local Instance ID:

Bash

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

To identify the virtual machine using its DC Provider VID, provide that identifier as the instance_id value:

Bash

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

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

Python Example Implementation

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


def resume_zseries_instance(
    api_key: str,
    instance_id: int | str,
) -> dict | None:
    """
    Resume a hibernated 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 resume 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.post(
        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."
        )

    try:
        result = resume_zseries_instance(
            api_key=api_key,
            instance_id=19,
        )

        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("Current Status:", data.get("current_status"))
            print("New Provider VID:", data.get("provider_vid"))

            # 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_resume.py

Windows PowerShell

PowerShell

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

The script submits the instance identifier and displays the returned status, message, current VM status, and new DC Provider VID. It avoids printing the full SSH command to the console.

Example Success Response

A successful request returns HTTP 200 OK with a JSON object containing the resumed instance's current status, new provider VID, SSH command, a descriptive message, and the response status.

HTTP Status: 200 OK

JSON

{
  "data": {
    "current_status": "Active",
    "provider_vid": "434218",
    "ssh_command": "ssh -i temporary.pem -o StrictHostKeyChecking=no [email protected]"
  },
  "message": "Instance 19 resumed successfully.",
  "status": "success"
}

The values above illustrate the response structure. The provider VID, SSH command, IP address, and instance identifier may differ in subsequent API responses.

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 confirming the resume operation.
data	Object	Contains the updated connection details and status of the resumed VM.

Instance Record Fields

The data object contains the information returned after the resume operation.

Field	Type	Description
data.current_status	String	The current VM status returned by the API. The example returns Active.
data.provider_vid	String	The new provider virtual machine identifier assigned after resuming.
data.ssh_command	String	The new SSH command returned for connecting to the resumed virtual machine.

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 is submitted in the JSON request body. The local Instance ID remains unchanged when the VM resumes, while the DC Provider VID resets with every restart.

Resume Eligibility

Only virtual machines in the Hibernated state can be resumed.

Before proceeding, the API verifies that the instance exists, belongs to the authenticated user, is hibernated, and that the user has sufficient account balance.

If the VM is already Active or is in another unsupported state, the API may return an invalid VM state error.

Provider VID and SSH Connection

When resuming succeeds, the provider assigns a new VID and a new SSH/IP connection command. These values are returned in the JSON response. Use the latest provider_vid and ssh_command returned by the API rather than relying on the values from before hibernation.

The SSH command can be used with the downloaded temporary.pem private key. Keep the private key and connection details secure.

Billing Information

Normal billing resumes when the VM becomes Active.

According to the supplied endpoint details, an initial charge of approximately 10 minutes of GPU compute plus NVMe storage is deducted when the VM resumes. Refer to the applicable Dataoorts billing details for the exact charges and billing policy.

Resume Workflow

The Z-Series resume 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 POST request to /api/v1/zseries/resume.
4. The API verifies that the VM exists, belongs to the authenticated user, is in the Hibernated state, and that the account has sufficient balance.
5. The provider resumes the virtual machine and assigns a new DC VID and SSH/IP connection command.
6. The VM status changes to Active.
7. Normal billing resumes, including the initial charge specified by the supplied billing policy.

Important Notes

1. Hibernated State Required: Only virtual machines in the Hibernated state can be resumed.

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

3. Instance Ownership: The virtual machine must belong to the authenticated user.

4. Account Balance: The account must have sufficient balance for the resume operation to proceed.

5. New Provider VID: The DC Provider VID resets with every restart. Save newly returned DC VID after successful GPU VM resume.

6. New SSH Connection: A new SSH/IP connection command is returned after resuming. Use the latest command and the downloaded temporary.pem private key.

7. Billing: Normal billing resumes when the VM becomes Active. The supplied endpoint notes specify an initial deduction of approximately 10 minutes of GPU compute plus NVMe storage.

8. Request Timeout: The Python example uses a timeout of 180 seconds. If the request times out, check the latest instance status before retrying because the result of the original request may be uncertain.

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

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

Your application should handle authentication failures, missing instance identifiers, invalid GPU VM Instance states, instances that cannot be found or accessed, insufficient account balance, provider capacity 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 resume 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": "Unify API Key Token is missing."
}

Ensure that the API key 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.

Invalid JSON

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid JSON Payload."
}

Ensure that the request body contains valid JSON.

Missing Instance ID

HTTP Status: 400 Bad Request

JSON

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

Provide the required instance_id field in the JSON request body.

Invalid VM State

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Cannot resume instance in 'Active' state."
}

This error is returned when the virtual machine is not in the Hibernated state. Check the latest instance status before submitting the VM resume request.

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 virtual machine belongs to the authenticated user.

Insufficient Balance

HTTP Status: 402 Payment Required

JSON

{
  "status": "error",
  "message": "Insufficient balance - Minimum $1.78 required."
}

Add sufficient funds to your account before submitting the resume request again. The amount shown is an example from the supplied error response.

Provider Capacity Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "Failed to resume instance, Capacity might be full."
}

This response indicates that the provider could not resume the virtual machine, potentially because capacity is unavailable. Check the instance status and try again later if appropriate.

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 valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
Request body is invalid	Send a valid JSON object containing instance_id.
Instance ID is missing	Provide the required instance_id field.
VM is not hibernated	Check the current GPU VM Instance status before attempting to resume it.
Instance is not found or access is denied	Verify the identifier and confirm that the VM belongs to the authenticated user.
Account balance is insufficient	Add sufficient funds in your account before retrying.
Provider returns 502	Check the instance status and provider capacity, then retry if appropriate.
Request times out	Retrieve the latest instance information before submitting another resume 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 resuming or API integration, Contact support team at [email protected].