Hibernate an Instance

This endpoint hibernates a running X-Series GPU virtual machine instance using its Instance ID or IP address.

Hibernate an Instance - Overview

The X-Series Hibernate API allows authenticated users to hibernate a running virtual machine using its IP address or the ID of its attached root disk, when only the root disk is attached.

Hibernation stops the instance while allowing it to remain in a hibernated state rather than permanently terminating it. This is useful when you temporarily do not need an instance but want to retain the ability to restart it later.

Hibernated instances are charged at a rate of $0.036 USD per hour.

Allow at least 25 minutes for a hibernated instance to restart. If the instance has a static IP address, that IP address will remain the same after hibernation.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/hibernate
Full URL	https://cloud.dataoorts.com/api/v1/xseries/hibernate
Authentication	Bearer Token
Content Type	application/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 request body must be sent as JSON.

Parameter	Type	Required	Description
id_or_ip	String	Yes	The instance's IP address or the ID of its attached root disk, when only the root disk is attached.

Provide appropriate identifier for instance you want to hibernate, Verify identifier before submitting request.

Request Examples

cURL - Use the following command to hibernate an instance using its IP address:

Bash

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

Replace YOUR_API_KEY and the example IP address with your actual values.

The id_or_ip parameter can also be set to the attached root disk ID when the root disk is the only attached disk, as supported by this endpoint.

Python Example Implementation:

Python

import os
import requests


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


def hibernate_xseries_instance(
    api_key: str,
    id_or_ip: str,
) -> dict:
    """
    Hibernate an X-Series virtual machine.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_ip: The instance IP address or eligible root disk ID.

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

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response cannot be decoded as JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "id_or_ip": id_or_ip,
    }

    response = requests.post(
        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."
        )

    try:
        result = hibernate_xseries_instance(
            api_key=api_key,
            id_or_ip="38.128.233.51",
        )

        print("Status:", result.get("status"))
        print("Current Status:", result.get("current_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 API response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python hibernate_instance.py

Windows PowerShell

PowerShell

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

The script submits the hibernation request and prints the status, message, current instance state, and rebate information returned by the API.

Example Success Response

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

JSON

{
  "current_status": "stopped",
  "message": "Instance hibernated successfully.",
  "rebate_credited": 0.00549,
  "status": "success"
}

The returned values depend on the instance and the result of the operation.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
current_status	String	The instance state reported by the API after the hibernation request. The example response returns stopped.
message	String	A message describing the result of the hibernation operation.
rebate_credited	Number	The rebate amount reported by API for operation, if applicable.

Hibernation Cost

The cost of a hibernated instance is $0.036 USD per hour.

This rate is intended for instances in the hibernated state. Review the applicable billing details for the instance when estimating total infrastructure costs.

Important Notes

1. Restart Time: Allow at least 25 minutes for a hibernated instance to restart. Plan workloads and deployment schedules accordingly.

2. Static IP Retention: If the instance has a static IP address, that IP address will remain the same after hibernation. This allows configurations that depend on the static IP to continue using the same address after the instance restarts.

3. Instance State: The example success response reports current_status as stopped. Treat this as the state returned by the API; do not assume that the instance is immediately ready to accept connections after a subsequent restart.

4. Correct Instance Identification: Verify the supplied IP address or eligible root disk ID before submitting the request. Use the appropriate identifier for the instance you want to hibernate.

5. Hibernation Is Not Termination: Hibernation and termination are different operations. Hibernation stops the instance while retaining its hibernated state, whereas termination permanently deletes the instance and its data. Use the Terminate an Instance endpoint only when permanent deletion is intended.

---

Error Handling

If request fails, the API may return an unsuccessful HTTP status code and a JSON response describing the error.

Common causes include auth failures, invalid identifiers, network errors, request timeouts, or server errors.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Handle such exceptions in your application rather than assuming every request succeeds.

If a request times out, the outcome of the operation may be uncertain. Check the instance state before submitting another hibernation request.

Get Help and Support

For assistance with instance hibernation, restart behavior, or API integration, contact the Dataoorts support team at [email protected]​.