Get All Instance Info

Get All Instance Info - Overview

The Yotta Series Instances API allows authenticated users to retrieve information about all pods associated with their Dataoorts account.

The endpoint returns a summary of instance counts by status, along with individual instance records containing the instance ID, Pod ID, GPU config, launch time, region, SSH command, total hourly cost, and hardware specs.

Use this endpoint to monitor Yotta infrastructure, track running and terminated pods, review GPU configs, and integrate instance information into custom dashboards or infrastructure management workflows.

Endpoint

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

This endpoint does not require any query parameters or a request body. Send a GET request with the required authentication header.

Request Examples

cURL - Use the following command to retrieve all Yotta Series instance records:

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

Replace YOUR_API_KEY with your actual Dataoorts Unify API key.

Python Example Implementation

The following example uses the requests library to retrieve all Yotta Series instances and display their summary counts, instance details, SSH command, and hardware specifications.

Install the required dependency:

pip install requests

import os
import requests


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


def list_yotta_instances(api_key: str) -> dict | None:
    """
    Retrieve all Yotta Series instance records and status counts.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        The JSON response containing instance records and counts,
        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",
    }

    response = requests.get(
        API_URL,
        headers=headers,
        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 = list_yotta_instances(api_key)

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

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

            print("\nInstance Summary")
            print("Pending:", counts.get("pending", 0))
            print("Running:", counts.get("running", 0))
            print("Terminated:", counts.get("terminated", 0))
            print("Total:", counts.get("total", 0))

            print("\nInstance Records")

            for instance in result.get("data", []):
                specs = instance.get("specs", {})

                print("-" * 40)
                print("Instance ID:", instance.get("instance_id"))
                print("Pod ID:", instance.get("pod_id"))
                print("GPU Configuration:", instance.get("gpu_config"))
                print("Status:", instance.get("status"))
                print("Region:", instance.get("region"))
                print("Launch Time (UTC):", instance.get("launch_time_utc"))
                print("SSH Command:", instance.get("ssh_command"))
                print(
                    "Total Hourly Cost:",
                    instance.get("total_hourly_cost"),
                )
                print("RAM (GB):", specs.get("ram_gb"))
                print("Storage (GB):", specs.get("storage_gb"))
                print("vCPU:", specs.get("v_cpu"))

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

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python yotta_instances.py

Windows PowerShell

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

The script displays the instance counts first, followed by each instance's ID, Pod ID, GPU configuration, status, region, launch time, SSH command, total hourly cost, and hardware specifications.

Example Success Response

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

{
  "counts": {
    "pending": 0,
    "running": 2,
    "terminated": 4,
    "total": 6
  },
  "data": [
    {
      "gpu_config": "2x NVIDIA_H200_141G",
      "instance_id": 6,
      "launch_time_utc": "Wed, 25 Feb 2026 10:28:26 GMT",
      "pod_id": "417387381247988075",
      "region": "Pending",
      "specs": {
        "ram_gb": null,
        "storage_gb": null,
        "v_cpu": null
      },
      "ssh_command": "Pending",
      "status": "running",
      "total_hourly_cost": 4.38
    },
    {
      "gpu_config": "1x NVIDIA_H200_141G",
      "instance_id": 5,
      "launch_time_utc": "Wed, 25 Feb 2026 10:28:08 GMT",
      "pod_id": "417387307231109936",
      "region": "Pending",
      "specs": {
        "ram_gb": null,
        "storage_gb": null,
        "v_cpu": null
      },
      "ssh_command": "Pending",
      "status": "running",
      "total_hourly_cost": 2.19
    },
    {
      "gpu_config": "1x NVIDIA_H200_141G",
      "instance_id": 4,
      "launch_time_utc": "Wed, 25 Feb 2026 07:46:35 GMT",
      "pod_id": "417346650508649256",
      "region": "Pending",
      "specs": {
        "ram_gb": null,
        "storage_gb": null,
        "v_cpu": null
      },
      "ssh_command": "N/A",
      "status": "terminated",
      "total_hourly_cost": 2.19
    },
    {
      "gpu_config": "1x NVIDIA_GeForce_RTX_4090_24G",
      "instance_id": 3,
      "launch_time_utc": "Tue, 24 Feb 2026 13:58:05 GMT",
      "pod_id": "417077758964028368",
      "region": "North Carolina (us-east-1)",
      "specs": {
        "ram_gb": 115,
        "storage_gb": 735,
        "v_cpu": 30
      },
      "ssh_command": "N/A",
      "status": "terminated",
      "total_hourly_cost": 0.567
    },
    {
      "gpu_config": "1x NVIDIA_GeForce_RTX_4090_24G",
      "instance_id": 2,
      "launch_time_utc": "Tue, 24 Feb 2026 13:19:53 GMT",
      "pod_id": "417068144331608466",
      "region": "Pending",
      "specs": {
        "ram_gb": null,
        "storage_gb": null,
        "v_cpu": null
      },
      "ssh_command": "N/A",
      "status": "terminated",
      "total_hourly_cost": 0.42
    },
    {
      "gpu_config": "1x NVIDIA_GeForce_RTX_4090_24G",
      "instance_id": 1,
      "launch_time_utc": "Tue, 24 Feb 2026 12:35:40 GMT",
      "pod_id": "417057019242238332",
      "region": "Pending",
      "specs": {
        "ram_gb": null,
        "storage_gb": null,
        "v_cpu": null
      },
      "ssh_command": "N/A",
      "status": "terminated",
      "total_hourly_cost": 0.42
    }
  ],
  "message": "Yotta instances list retrieved successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance counts, GPU configurations, statuses, connection details, hardware specifications, and costs 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`.
`message`	String	A descriptive message about the result of the request.
`counts`	Object	Contains summary counts for the reported instance statuses and the total number of instances.
`data`	Array of objects	Contains individual Yotta Series pod records returned by the API.

Instance Counts

The counts object provides an overview of instance states.

Field	Type	Description
`counts.pending`	Integer	Number of instances reported as pending in the summary.
`counts.running`	Integer	Number of instances reported as running.
`counts.terminated`	Integer	Number of instances reported as terminated.
`counts.total`	Integer	Total number of instances reported in the summary.

Instance Record Fields

Each object in the data array represents an instance record.

Field	Type	Description
`instance_id`	Integer	The identifier assigned to the instance.
`pod_id`	String	The identifier assigned to the Yotta pod.
`gpu_config`	String	The GPU configuration associated with the instance, such as `2x NVIDIA_H200_141G`.
`status`	String	The instance status returned by the API, such as `running` or `terminated`.
`region`	String	The region associated with the instance. The example includes `Pending` and `North Carolina (us-east-1)`.
`launch_time_utc`	String	The instance launch timestamp in UTC.
`ssh_command`	String	The SSH connection command or availability value returned by the API. The example includes `Pending` and `N/A`.
`total_hourly_cost`	Float	The total hourly cost reported for the instance.
`specs`	Object	Contains the RAM, storage, and vCPU specifications returned for the instance or pod.

Hardware Specification Fields

The specs object contains the hardware details reported for each instance.

Field	Type	Description
`specs.ram_gb`	Number or Null	RAM capacity in GB, or `null` when no value is available in the response.
`specs.storage_gb`	Number or Null	Storage capacity in GB, or `null` when no value is available in the response.
`specs.v_cpu`	Number or Null	The vCPU value returned for the instance, or `null` when no value is available in the response.

Understanding Instance Information

Instance Status

The status field indicates the state reported for each instance. The example response includes running and terminated records, while the summary also provides a pending count.

Use the returned status to categorize instances in your application. The counts object provides summary categories, while each record contains its own status value.

SSH Command Availability

The ssh_command field contains the SSH command or availability value returned by the API.

In the example response:

Pending is returned for running instances whose SSH command is not yet available in the response.
N/A is returned for terminated instances.

Handle these values in your application. Do not treat Pending or N/A as executable SSH commands.

Region Information

The region field provides the region information returned for an instance.

In the example response, some instances return Pending, while another returns North Carolina (us-east-1). Handle Pending as an unavailable region value rather than assuming a specific region.

Hardware Specifications

The specs object provides the RAM, storage, and vCPU values returned for each instance.

These fields may contain null when specifications are unavailable in the response. Handle null values instead of assuming that all hardware details are populated.

Hourly Cost

The total_hourly_cost field reports the total hourly cost returned for an instance. The above example response includes costs such as 4.38, 2.19, and 0.42. Use the returned value when displying pod cost info.

Important Notes

1. Instance Status: The response can contain running and terminated instances. Do not assume every returned instance is currently running.

2. SSH Availability: Handle Pending and N/A values in ssh_command appropriately. Only use a valid SSH command when it is available.

3. Region Information: The region field may return Pending. Do not assume a region is available when the response does not provide one.

4. Hardware Specifications: The RAM, storage, and vCPU fields may return null. Handle missing values in your application.

5. Historical Records: The response can include terminated instances alongside running instances. Use the returned status field to distinguish between them.

6. Pricing Information: The total_hourly_cost field represents the hourly cost reported for each instance. Use the returned value when displaying cost information.

7. Current State: Instance details reflect the information returned at the time of the request. Retrieve the latest information when status or connection availability is 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 and an error response.

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

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks response content type and handles JSON decoding errors before processing pod records.

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.
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 JSON decoding error before accessing response fields.
Hardware fields contain `null`	Handle missing values instead of assuming spes are available.
SSH command is `Pending` or `N/A`	Check latest pod information before attempting to connect.

Get Help and Support

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