Single Instance Info

Single Instance Info - Overview

The Atlas Series Single Instance API allows authenticated users to retrieve detailed information and the current status of a single Atlas Series instance using either its instance ID or its public IP address.

The endpoint returns the instance configuration, container ID, launch time, public IP address, region, SSH connection details, hardware specifications, total hourly cost, cost breakdown, and last billed time.

Use this endpoint to inspect a specific Atlas instance, review its current or historical status, and retrieve its associated pricing and configuration information.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/atlas/instance`
Full URL	`https://cloud.dataoorts.com/api/v1/atlas/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_ip query parameter to identify the Atlas instance.

Parameter	Type	Required	Description
`id_or_ip`	String	Yes	The instance ID or public IP address of the Atlas Series Pod whose information you want to retrieve.

Example Request

GET /api/v1/atlas/instance?id_or_ip=11

You can provide an instance ID or a public IP address as the parameter value.

Request Examples

cURL - Use the following command to retrieve info about a specific Atlas pod using its Pod ID:

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

To retrieve information using the instance's public IP address, replace 11 with the relevant IP address.

Replace YOUR_API_KEY with your actual Dataoorts Unify API key.

Python Example Implementation

The following example uses the requests library to retrieve information about a single Atlas instance using its instance ID or public IP address. 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/atlas/instance"


def get_atlas_instance_info(api_key: str, id_or_ip: str) -> dict:
    """
    Retrieve detailed information about a single Atlas instance.

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

    Returns:
        dict: The JSON response containing instance details.

    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",
    }

    params = {
        "id_or_ip": id_or_ip,
    }

    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():
        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_instance_info(
            api_key=api_key,
            id_or_ip="11",
        )

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

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

        print("\nAtlas Instance Details")
        print("Instance ID:", data.get("instance_id"))
        print("Configuration:", data.get("config_name"))
        print("Container ID:", data.get("container_id"))
        print("Status:", data.get("status"))
        print("Public IP:", data.get("public_ip"))
        print("Region:", data.get("region"))
        print("Launch Time:", data.get("launch_time"))
        print("SSH Port:", data.get("ssh_port"))
        print("SSH User:", data.get("ssh_user"))
        print("Total Hourly Cost:", data.get("total_hourly_cost"))
        print("Last Billed Time:", data.get("last_billed_time"))

        breakdown = data.get("breakdown", {})
        print("\nCost Breakdown")
        print("Compute Cost:", breakdown.get("compute_cost"))
        print("Storage Cost:", breakdown.get("storage_cost"))

        specs = data.get("specs", {})
        print("\nHardware Specifications")
        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_instance_info.py

Windows PowerShell

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

The script retrieves the requested instance information and displays its configuration, status, connection details, cost breakdown, and hardware specifications.

Example Success Response

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

HTTP Status: 200 OK

{
  "data": {
    "breakdown": {
      "compute_cost": 2.49,
      "storage_cost": 0.4096
    },
    "config_name": "1xB200-180GB",
    "container_id": "container-u0mfkp8a4d16qe87",
    "instance_id": 11,
    "last_billed_time": null,
    "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
    },
    "ssh_port": 22,
    "ssh_user": "ubuntu",
    "status": "terminated",
    "total_hourly_cost": 2.8996
  },
  "message": "Terminated instance history retrieved for you successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance details, statuses, identifiers, 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 Atlas Series instance.

Instance Record Fields

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

Field	Type	Description
`data.instance_id`	Integer	The identifier assigned to the instance.
`data.config_name`	String	The name of the instance configuration, such as `1xB200-180GB`.
`data.container_id`	String	The container identifier associated with the instance.
`data.status`	String	The instance status returned by the API, such as `terminated`.
`data.public_ip`	String	The public IP address returned for the instance. The example returns `N/A`.
`data.region`	String	The region associated with the pod, such as `US`.
`data.launch_time`	String	The launch timestamp reported for the instance.
`data.ssh_port`	Integer	The SSH port returned by the API. The example uses port `22`.
`data.ssh_user`	String	The SSH username returned for the instance.
`data.total_hourly_cost`	Float	The total hourly charge reported for the instance's GPU and storage volume costs.
`data.last_billed_time`	String or Null	The last billed timestamp returned by the API, or `null` when no timestamp is provided.
`data.breakdown`	Object	Contains the compute and storage cost components.
`data.specs`	Object	Contains the GPU, operating system image, and storage specifications reported for the instance.

Cost Breakdown Fields

The breakdown object provides a breakdown of the instance's hourly costs.

Field	Type	Description
`data.breakdown.compute_cost`	Number	The compute cost reported for the instance.
`data.breakdown.storage_cost`	Number	The storage cost reported for the instance.

In the example response, the compute cost is 2.49 and the storage cost is 0.4096, giving a total hourly cost of 2.8996.

Hardware Specification Fields

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

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

Understanding Instance Information

Instance Identification

Use the id_or_ip query parameter to identify the Atlas instance you want to retrieve. The endpoint supports lookup by instance ID or public IP address.

The response includes instance_id and container_id to help identify the returned instance record.

Instance Status

The status field indicates the state reported for the requested instance. The example response shows a terminated instance.

The response message in the example is Terminated instance history retrieved for you successfully. This indicates that the returned information can include terminated-instance history.

Public IP and SSH Information

The public_ip field provides the IP address returned by the API. In the example response, its value is N/A.

The ssh_port and ssh_user fields provide the SSH connection details returned by the API. Check the instance status and public IP before attempting to connect. A terminated instance with a public IP value of N/A should not be treated as ready for SSH access.

Hourly Cost and Billing Information

The total_hourly_cost field reports the total hourly charge associated with the instance. The breakdown object separates this amount into compute and storage costs.

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

The last_billed_time field provides the last billed timestamp when available. In the example response, its value is null.

Important Notes

1. Instance Lookup: Provide an instance ID or public IP address using the id_or_ip query parameter.

2. Terminated Instances: The response may include historical information for terminated instances. Check the returned status before attempting to connect to an instance.

3. Public IP Availability: The API may return N/A for the public IP address of a terminated instance.

4. SSH Details: Use the returned ssh_port and ssh_user when reviewing connection details. Confirm the instance is in a suitable state before attempting SSH access.

5. Cost Breakdown: The breakdown object separates compute and storage costs. The total_hourly_cost field reports the combined hourly charge for GPU and storage volume costs.

6. Last Billed Time: The last_billed_time field may be null. Handle this value in your application rather than assuming a timestamp is always present.

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

Scenario	Recommended Handling
API key is missing	Set the `DATAOORTS_API_KEY` environment variable.
Authentication fails	Verify that API Key is valid & included in `Authorization` header.
Instance ID or public IP is invalid	Verify that `id_or_ip` parameter 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 and handle it without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.
`last_billed_time` is `null`	Handle missing timestamp witout assuming billing time available.

Get Help and Support

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