Get All Available Offers

Get All Available Offers - Overview

The Orion Series Offers API allows authenticated users to retrieve all available GPU instance offers on the Dataoorts Orion platform.

The endpoint returns GPU configurations along with their hourly pricing, instance type, GPU count, hardware specifications, available deployment regions, and supported operating system images.

Use this endpoint to compare GPU configurations, estimate infrastructure costs, identify deployment regions, and select suitable offers for your instance provisioning workflows.

The response includes the total number of offers, the pricing currency, and the available configuration details.

Important Note: This endpoint is subject to strict Orion-specific rate limits. Implement caching in your application to avoid unnecessary requests and reduce the risk of reaching the rate limit.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/orion/offers`
Full URL	`https://cloud.dataoorts.com/api/v1/orion/offers`
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 available Orion GPU offers:

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/orion/offers" \
  --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 Orion offers and cache the response in memory. The example uses a client-side cache duration of five minutes to reduce repeated requests. You can adjust this duration according to your application's freshness requirements.

Install the required dependency:

pip install requests

import os
import time
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/orion/offers"
CACHE_TTL_SECONDS = 300

_offers_cache = {}


def get_orion_offers(api_key: str) -> dict:
    """
    Retrieve and cache available Orion GPU offers.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response containing available offers.

    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.
    """
    now = time.monotonic()
    cached = _offers_cache.get(api_key)

    if cached and now - cached["timestamp"] < CACHE_TTL_SECONDS:
        return cached["data"]

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
    }

    response = requests.get(
        API_URL,
        headers=headers,
        timeout=30,
    )

    response.raise_for_status()

    try:
        data = response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc

    _offers_cache[api_key] = {
        "timestamp": time.monotonic(),
        "data": data,
    }

    return data


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

        print("Status:", result.get("status"))
        print("Count:", result.get("count"))
        print("Currency:", result.get("currency"))
        print("Message:", result.get("message"))

        print("\nAvailable Orion Offers:")

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

            print("-" * 40)
            print("Offer ID:", offer.get("offer_id"))
            print("GPU:", offer.get("gpu_name"))
            print("GPU Count:", offer.get("gpu_count"))
            print("Instance Type:", offer.get("instance_type"))
            print("Hourly Price:", offer.get("hourly_price"))
            print("Currency:", result.get("currency"))
            print("Specifications:", specs)
            print("Available Regions:", offer.get("available_regions"))
            print("Supported Images:", offer.get("supported_images"))

    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 orion_offers.py

Windows PowerShell

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

The example caches the response in the current Python process. Repeated calls using the same API key reuse the cached data until the cache expires. This in-memory cache is not shared across separate processes or application servers.

Example Success Response

A successful request returns a JSON object containing the total number of offers, pricing currency, a descriptive message, the available offers, and the response status.

HTTP Status: 200 OK

{
  "count": 19,
  "currency": "USD",
  "message": "Live Orion GPU offers retrieved for you successfully.",
  "offers": [
    {
      "available_regions": [
        {
          "country_code": "US",
          "name": "USA-Desmoines-1",
          "region_id": "desmoines-usa-1"
        }
      ],
      "gpu_count": 1,
      "gpu_name": "A100_80G",
      "hourly_price": 1.26294,
      "instance_type": "VM",
      "offer_id": "A100_80Gx1",
      "specs": {
        "nvlink": false,
        "ram_gb": 100,
        "storage_gb": 625,
        "vcpu": 14,
        "vram_gb": 80
      },
      "supported_images": [
        "ubuntu22.04_cuda12.6_shade_os"
      ]
    },
    {
      "available_regions": [
        {
          "country_code": "CA",
          "name": "CAN-Montreal-2",
          "region_id": "montreal-canada-2"
        }
      ],
      "gpu_count": 1,
      "gpu_name": "H100",
      "hourly_price": 1.93515,
      "instance_type": "VM",
      "offer_id": "H100x1",
      "specs": {
        "nvlink": false,
        "ram_gb": 180,
        "storage_gb": 850,
        "vcpu": 28,
        "vram_gb": 80
      },
      "supported_images": [
        "ubuntu22.04_cuda12.8_shade_os",
        "ubuntu22.04_cuda12.2_shade_os",
        "ubuntu22.04"
      ]
    }
  ],
  "status": "success"
}

The example is abbreviated to show two representative offers. The actual response can contain additional offers, and the count field reports the total number returned by the API.

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response returns `success`.
`count`	Integer	Total number of offers returned by the API.
`currency`	String	Currency used for the offer prices, such as `USD`.
`message`	String	A descriptive message about the result of the request.
`offers`	Array of objects	Contains the available Orion GPU instance configurations.

Offer Fields

Each object in the offers array describes an individual GPU instance configuration.

Field	Type	Description
`offer_id`	String	Identifier for GPU offer, such as `A100_80Gx1`, `H100x1`.
`instance_type`	String	Type of instance offered, such as `VM` or `BARE METAL`.
`gpu_name`	String	GPU model or configuration name.
`gpu_count`	Integer	Number of GPUs included in the offer.
`hourly_price`	Float	Hourly price of the offer in the currency specified by the top-level `currency` field.
`available_regions`	Array of objects	Regions in which the offer is available.
`specs`	Object	Hardware specifications associated with the offer.
`supported_images`	Array of strings	OS image identifiers supported by the offer.

Available Region Fields

Each entry in available_regions identifies a deployment region for the offer.

Field	Type	Description
`country_code`	String or `null`	Country code associated with the region, when provided.
`name`	String	Display name of the region.
`region_id`	String	Region identifier used to reference the deployment region.

The country_code field may be null for some regions. Your application should handle null values rather than assuming every region has a country code.

Hardware Specification Fields

The specs object contains the hardware specifications reported for the offer.

Field	Type	Description
`specs.nvlink`	Boolean	Indicates whether NVLink is reported as supported by the configuration.
`specs.ram_gb`	Number	System RAM capacity in GB.
`specs.storage_gb`	Number	Storage capacity in GB.
`specs.vcpu`	Number	Number of virtual CPU cores reported for the configuration.
`specs.vram_gb`	Number	GPU video memory capacity in GB, as reported by the API.

Supported OS Images

The supported_images field contains the OS image identifiers supported by the particular offer.

For example:

"supported_images": [
  "ubuntu22.04_cuda12.8_shade_os",
  "ubuntu22.04_cuda12.2_shade_os",
  "ubuntu22.04"
]

Use this list when selecting an operating system image for an instance. Ensure the selected image identifier matches one supported by the intended offer.

Understanding Orion GPU Offers

Each offer combines a GPU configuration, hardware specifications, hourly price, available regions, and supported OS images.

For example, an offer with "offer_id": "H100x1" identifies a configuration with one H100 GPU. Its hourly_price indicates the hourly price returned by the API, while available_regions identifies its available deployment locations.

Use offer_id to identify the offer in a compatible Orion provisioning workflow, and review its supported images and regions before selecting it.

Important Notes

1. Caching Is Important: This endpoint has strict rate limits specific to the Orion Series. Cache the offers response and avoid repeatedly calling the endpoint when cached data is sufficient.

2. Hourly Pricing: The hourly_price value is expressed in the currency returned by the API. Use the top-level currency field when displaying or calculating prices.

3. Region Selection: An offer may include one or more entries in available_regions. Review the returned region IDs before choosing where to deploy an instance.

4. Supported Images: Use an OS image identifier listed in supported_images when selecting an image for a compatible GPU Instance offer.

5. Dynamic Availability: Offers, prices, regions, and supported images may change. Refresh cached data when your application needs updated information.

6. Offer Listing Only: This endpoint retrieves offer information. It does not launch an instance by itself.

Error Handling

If request fails, API may return unsuccessful HTTP status code and JSON response containing an error message.

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. Do not assume that an error response contains the same fields as a successful response.

Get Help and Support

For assistance with Orion GPU offers or API integration, contact the support team at [email protected].