Get All Instance Info

Get All Instance Info - Overview

The Atlas Series Instances API allows authenticated users to retrieve detailed information and the current status of all Atlas Series instances associated with their Dataoorts account.

The endpoint returns a summary of instance counts by status, along with individual instance records containing the instance ID, configuration name, container ID, launch time, public IP address, region, total hourly cost, and hardware specifications.

Use this endpoint to monitor Atlas infrastructure, track running and terminated instances, review instance configurations & integrate pod information into custom dashboards or infrastructure management workflows.

Endpoint

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

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/atlas/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 Atlas instances and display their summary counts, instance details, and hardware specifications.

Install the required dependency:

pip install requests

import os
import requests


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


def get_atlas_instances(api_key: str) -> dict:
    """
    Retrieve all Atlas Series instance records and status counts.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response containing instance records
              and status counts.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response is not JSON or cannot be decoded.
    """
    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():
        raise ValueError(
            "The API returned a non-JSON response: "
            f"{response.text[:500]}"
        )

    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_atlas_instances(api_key)

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

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

        print("\nInstance Summary")
        print("Other:", counts.get("other", 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("Configuration:", instance.get("config_name"))
            print("Container ID:", instance.get("container_id"))
            print("Status:", instance.get("status"))
            print("Public IP:", instance.get("public_ip"))
            print("Region:", instance.get("region"))
            print("Launch Time:", instance.get("launch_time"))
            print(
                "Total Hourly Cost:",
                instance.get("total_hourly_cost"),
            )
            print("GPU Count:", specs.get("gpu_count"))
            print("OS Image:", specs.get("os_image"))
            print("Storage (GB):", specs.get("storage_gb"))

    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

export DATAOORTS_API_KEY="YOUR_API_KEY"
python atlas_instances.py

Windows PowerShell

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

The script displays the instance counts first, followed by each instance's configuration, status, container ID, public IP, region, launch time, 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.

HTTP Status: 200 OK

{
  "counts": {
    "other": 0,
    "running": 1,
    "terminated": 1,
    "total": 2
  },
  "data": [
    {
      "config_name": "1xB200-180GB",
      "container_id": "container-u0mfkp8a4d16qe87",
      "instance_id": 11,
      "launch_time": "Wed, 28 Jan 2026 14:19:29 GMT",
      "public_ip": "N/A",
      "region": "US",
      "specs": {
        "gpu_count": 1,
        "os_image": "Ubuntu-Torch",
        "storage_gb": 10240
      },
      "status": "terminated",
      "total_hourly_cost": 2.8996
    },
    {
      "config_name": "1xB200-180GB",
      "container_id": "container-cqgwyg5vn134o96z",
      "instance_id": 10,
      "launch_time": "Wed, 28 Jan 2026 14:18:36 GMT",
      "public_ip": "38.127.229.94",
      "region": "US",
      "specs": {
        "gpu_count": 1,
        "os_image": "Ubuntu-Torch",
        "storage_gb": 10240
      },
      "status": "running",
      "total_hourly_cost": 2.8996
    }
  ],
  "message": "Atlas instances list retrieved for you successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance counts, configurations, statuses, IP addresses, 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 status`success`.
`message`	String	A descriptive message about the result of the request.
`counts`	Object	Contains summary counts for instance statuses and the total number of instances reported.
`data`	Array of objects	Contains individual Atlas Series pod record returned by the API.

Instance Counts

The counts object provides an overview of the instance states.

Field	Type	Description
`counts.other`	Integer	Number of instances included in the `other` status category.
`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 Atlas instance record.

Field	Type	Description
`instance_id`	Integer	The identifier assigned to the instance.
`config_name`	String	The name of the instance configuration, such as `1xB200-180GB`.
`container_id`	String	The container identifier associated with the instance.
`status`	String	The instance status returned by the API, such as `running` or `terminated`.
`public_ip`	String	The public IP address returned for the instance. Terminated instances may return `N/A`.
`region`	String	The region associated with the instance, such as `US`.
`launch_time`	String	The launch timestamp reported for the instance.
`total_hourly_cost`	Float	The total hourly charge reported for the instance's GPU and storage costs.
`specs`	Object	Contains the GPU, operating system image, and storage specifications reported for the instance.

Hardware Specification Fields

The specs object contains the hardware and operating system details associated with each instance.

Field	Type	Description
`specs.gpu_count`	Integer	Number of GPUs associated with the instance.
`specs.os_image`	String	OS image associated with the pod, such as `Ubuntu-Torch`.
`specs.storage_gb`	Integer	Storage capacity specified for the instance, in gigabytes.

Understanding Instance Information

Instance Status

The status field indicates the state reported for each instance. The example response includes running and terminated instances.

Use the returned status to categorize instances in your application. The counts object provides summary categories, while individual records contain their own status values.

Public IP Availability

The public_ip field contains the public IP address returned by the API.

In the example response, the terminated instance has a public_ip value of N/A, while the running instance has a public IP address.

Check the instance status and returned IP address before attempting to connect to an instance.

Instance Configuration

The config_name field identifies the Atlas GPU configuration used by the instance. The specs object provides its GPU count, operating system image, and storage capacity.

Use these fields to display configuration information in dashboards or infrastructure management tools.

Hourly Cost

The total_hourly_cost field reports the total hourly charge associated with the instance's GPU and storage volume costs.

All other instance resources are provided at no additional cost. The total hourly charge applies only to the GPU cost and the storage volume cost; all remaining resources are free.

The example response reports an hourly cost of 2.8996. The actual value may differ depending on the instance configuration.

Important Notes

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

2. Public IP: A terminated instance may return N/A for public_ip. Check the returned status before attempting to connect.

3. Instance Identification: Use instance_id and container_id to identify the records returned by the API.

4. Hardware Specifications: Use the specs object to display the GPU count, OS image, and storage capacity associated with each instance.

5. Pricing Information: The total_hourly_cost field represents the total hourly charge for GPU and storage volume costs. All remaining resources are provided at no additional cost.

6. Current State: Instance details reflect the information returned at the time of the request. Retrieve the latest information when the current status, IP address, or pricing is important.

7. 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 check the response content type & handles JSON decoding errors before processing pod records.

Get Help and Support

For assistance with Atlas instance info or API integration, Contact the support team at [email protected].