Single Instance Info

Single Instance Info - Overview

The Yotta Series Single Instance API allows authenticated users to retrieve detailed information about a single Yotta Series pod using either its instance ID or its Pod ID.

The endpoint returns the instance status, launch time, next billing cycle, operating system image, GPU specifications, connection details, and hourly cost breakdown.

Use this endpoint to inspect a specific Yotta instance, check its provisioning and connection information, and review its associated compute and storage costs.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/yotta/instance`
Full URL	`https://cloud.dataoorts.com/api/v1/yotta/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.

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_pid query parameter to identify the Yotta Series instance.

Parameter	Type	Required	Description
`id_or_pid`	Integer or String	Yes	The instance ID or Pod ID of the Yotta Series pod whose information you want to retrieve.

Example Request

GET /api/v1/yotta/instance?id_or_pid=5

You can provide either the instance ID or the Pod ID as the parameter value.

Request Examples

cURL - Use the following command to retrieve information about a specific instance using its instance ID:

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

To retrieve information using the Pod ID, replace 5 with the relevant Pod ID, For example:

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

Replace YOUR_API_KEY with your actual Unify API key.

Python Example Implementation

The following example uses the requests library to retrieve information about a single Yotta Series instance using its instance ID or Pod ID. It handles unsuccessful HTTP responses and validates the response format before processing the returned data.

Install the required dependency:

pip install requests

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/yotta/instance"


def get_yotta_instance(api_key: str, id_or_pid: int | str) -> dict | None:
    """
    Retrieve detailed information about a single Yotta Series pod.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_pid: The instance ID or Pod ID.

    Returns:
        The JSON response containing instance details,
        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_pid": id_or_pid,
    }

    response = requests.get(
        API_URL,
        headers=headers,
        params=params,
        timeout=60,
    )

    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_yotta_instance(
            api_key=api_key,
            id_or_pid=5,
        )

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

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

            print("\nYotta Instance Details")
            print("Instance ID:", data.get("instance_id"))
            print("Status:", data.get("status"))
            print("OS Image:", data.get("os_image"))
            print("Launch Time (UTC):", data.get("launch_time_utc"))
            print(
                "Next Billing Cycle (UTC):",
                data.get("next_billing_cycle_utc"),
            )

            connection = data.get("connection", {})
            print("\nConnection Details")
            print("Pod ID:", connection.get("pod_id"))
            print("Region:", connection.get("region"))
            print("SSH Command:", connection.get("ssh_command"))

            specs = data.get("specs", {})
            print("\nHardware Specifications")
            print("GPU Model:", specs.get("gpu_model"))
            print("GPU Count:", specs.get("gpu_count"))
            print("RAM (GB):", specs.get("ram_gb"))
            print("Storage (GB):", specs.get("storage_gb"))
            print("vCPU:", specs.get("v_cpu"))

            costs = data.get("cost_breakdown", {})
            print("\nHourly Cost Breakdown")
            print("Compute:", costs.get("compute_hourly"))
            print("Storage:", costs.get("storage_hourly"))
            print("Total:", costs.get("total_hourly"))

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

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

Set your Unify API key in env secrets before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python yotta_instance_info.py

Windows PowerShell

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

The script retrieves the requested pod information and displays its status, connection details, hardware specifications, billing timestamps, and hourly cost breakdown.

Example Success Response

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

{
  "data": {
    "connection": {
      "pod_id": "417387307231109936",
      "region": "Pending",
      "ssh_command": "Pending"
    },
    "cost_breakdown": {
      "compute_hourly": 2.19,
      "storage_hourly": 0.0,
      "total_hourly": 2.19
    },
    "instance_id": 5,
    "launch_time_utc": "Wed, 25 Feb 2026 10:28:08 GMT",
    "next_billing_cycle_utc": "Wed, 25 Feb 2026 10:38:08 GMT",
    "os_image": "pytorch:2.9.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
    "specs": {
      "gpu_count": 1,
      "gpu_model": "NVIDIA_H200_141G",
      "ram_gb": "Pending",
      "storage_gb": "Pending",
      "v_cpu": "Pending"
    },
    "status": "running"
  },
  "message": "Pod details retrieved successfully.",
  "status": "success"
}

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

Response Fields

Field	Type	Description
`status`	String	Indicates result of the API request. A successful response returns `success`.
`message`	String	A descriptive message about the result of the request.
`data`	Object	Contains the details of the requested Yotta Series pod.

Instance Record Fields

The data object contains the information returned for the requested pod.

Field	Type	Description
`data.instance_id`	Integer	The identifier assigned to the instance.
`data.status`	String	The Pod status returned by API, such as `running`.
`data.os_image`	String	The operating system or software image associated with the pod.
`data.launch_time_utc`	String	The instance launch timestamp in UTC.
`data.next_billing_cycle_utc`	String	The next billing cycle timestamp in UTC.
`data.connection`	Object	Contains the Pod ID, region, and SSH command info.
`data.cost_breakdown`	Object	Contains the hourly compute cost, storage cost, and total hourly cost.
`data.specs`	Object	Contains the GPU and hardware specifications returned for the pod.

Connection Fields

The connection object contains the connection details returned for the pod.

Field	Type	Description
`data.connection.pod_id`	String	The identifier assigned to the Yotta pod.
`data.connection.region`	String	The region information returned for the pod. The example returns `Pending`.
`data.connection.ssh_command`	String	The SSH command or availability value returned by the API. The example returns `Pending`.

Cost Breakdown Fields

The cost_breakdown object provides the hourly cost details for the pod.

Field	Type	Description
`data.cost_breakdown.compute_hourly`	Float	The hourly compute cost reported for the pod.
`data.cost_breakdown.storage_hourly`	Float	The hourly storage cost reported for the pod.
`data.cost_breakdown.total_hourly`	Float	The total hourly cost reported for the pod.

Hardware Specification Fields

The specs object contains the hardware specifications returned for the pod.

Field	Type	Description
`data.specs.gpu_model`	String	The GPU model associated with the pod, such as `NVIDIA_H200_141G`.
`data.specs.gpu_count`	Integer	The number of GPUs associated with the pod.
`data.specs.ram_gb`	String or Number	The RAM capacity in GB, or a value such as `Pending` when returned by the API.
`data.specs.storage_gb`	String or Number	The storage capacity in GB, or a value such as `Pending` when returned by the API.
`data.specs.v_cpu`	String or Number	The vCPU value returned for the pod, or a value such as `Pending`.

Understanding Instance Information

Instance Identification

Use the id_or_pid query parameter to identify the Yotta Series pod you want to retrieve.

The endpoint supports lookup by either the instance ID or the Pod ID. The response returns the instance_id and connection.pod_id fields to identify the instance and its associated pod.

Instance Status

The status field indicates the state returned for requested instance. In example response, status is running.

Use the returned status to determine how to display the instance in your application. Check the latest instance information when the current state is important.

Connection Information

The connection object provides the Pod ID, region, and SSH command information.

In the example response, both region and ssh_command return Pending. Handle these values in your application and check the latest instance details before attempting to connect.

Hardware Specifications

The specs object provides the GPU model, GPU count, RAM, storage, and vCPU information.

In the example response, ram_gb, storage_gb, and v_cpu return Pending. Preserve and handle these values instead of assuming the specifications are immediately available.

Hourly Cost and Billing Information

The cost_breakdown object separates the reported hourly cost into compute and storage components.

The launch_time_utc field provides the launch timestamp, while next_billing_cycle_utc provides the next billing cycle timestamp. Both are returned in UTC Zone.

Important Notes

1. Instance Lookup: Provide either the instance ID or the Pod ID through the id_or_pid query parameter.

2. Instance Status: The response may report running while certain connection or hardware details still return Pending. Check the individual fields before using them.

3. SSH Connection: Do not treat Pending as an executable SSH command. Check the latest connection details before attempting to connect.

4. Hardware Specifications: Handle values such as Pending in the RAM, storage, and vCPU fields instead of assuming that all specifications are immediately available.

5. Cost Breakdown: Use compute_hourly, storage_hourly, and total_hourly to display the cost details returned by the API.

6. Billing Timestamps: The launch time and next billing cycle are returned in UTC. Account for the UTC timezone when displaying these timestamps to users.

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

If the request fails, the API may return an unsuccessful HTTP status code or a response that does not match the expected JSON format.

Your application should handle authentication failures, invalid instance identifiers, network errors, request timeouts, server errors, and unexpected response formats. Error codes & messages depend on API response.

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 returned instance details.

Scenario	Recommended Handling
API key is missing	Set the `DATAOORTS_API_KEY` environment variable.
Authentication fails	Verify that the API key is valid and included in the `Authorization` header.
Instance ID or Pod ID is invalid	Verify that `id_or_pid` identifies the intended pod.
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.
Connection or hardware fields return `Pending`	Handle the returned values and check the latest instance information when needed.

Get Help and Support

For assistance with Yotta pod information or API integration, Contact support team at [email protected].