Get All Available Offers

This endpoint retrieves all available GPU instance offers within the Nova Series ecosystem. It allows developers to query active compute configurations dynamically and filter results by contract type on-demand or spot.

Get All Available Instances to Deploy - Overview

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

This endpoint supports two pricing contract types: On-Demand and Spot. You can select the required offer type using the type query parameter. If no type is specified, API returns On-Demand offers by default.

Each offer includes the GPU model, GPU count, display name, instance type ID, region, and contract type. Use this endpoint to explore available GPU configurations, select an instance type, and integrate offer discovery into your infrastructure provisioning workflows.

Available offers and their associated regions may change over time. Retrieve the latest offers when selecting a configuration for a new instance.

Endpoint

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

HTTP

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 accepts an optional query parameter.

Parameter	Type	Required	Default	Description
type	String	No	on-demand	Pricing contract type to fetch, Supported values are on-demand and spot.

Supported Offer Types

Value	Description
on-demand	Retrieves available On-Demand GPU instance offers.
spot	Retrieves available Spot GPU instance offers.

If the type parameter is omitted, the API returns On-Demand offers.

Request Examples

1. Get All On-Demand Offers

cURL - Retrieve all available On-Demand GPU offers:

Bash

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

Since On-Demand is the default option, you do not need to specify the type parameter.

You can also explicitly select On-Demand offers:

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/nova/offers?type=on-demand" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

2. Get All Spot Offers

Use the type=spot query parameter to retrieve available Spot GPU offers.

Bash

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/nova/offers?type=spot" \
  --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 On-Demand or Spot offers. The offer_type parameter defaults to on-demand.

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/nova/offers"


def get_nova_offers(
    api_key: str,
    offer_type: str = "on-demand",
) -> dict:
    """
    Retrieve available Nova GPU instance offers.

    Args:
        api_key: Your Dataoorts Unify API key.
        offer_type: Offer contract type, either 'on-demand'
                    or 'spot'. Defaults to 'on-demand'.

    Returns:
        dict: The JSON response containing available offers.

    Raises:
        ValueError:
            If the specified offer type is invalid or the response
            cannot be decoded as JSON.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    offer_type = offer_type.lower()

    if offer_type not in {"on-demand", "spot"}:
        raise ValueError(
            "offer_type must be 'on-demand' or 'spot'."
        )

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

    params = {
        "type": offer_type,
    }

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

    response.raise_for_status()

    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:
        # Retrieve On-Demand offers by default.
        result = get_nova_offers(api_key)

        # To retrieve Spot offers instead, use:
        # result = get_nova_offers(api_key, offer_type="spot")

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

        print("\nAvailable Nova GPU Offers:")

        for offer in result.get("offers", []):
            print("-" * 40)
            print("Display Name:", offer.get("display_name"))
            print("GPU Model:", offer.get("gpu_model"))
            print("GPU Count:", offer.get("gpu_count"))
            print("Instance Type ID:", offer.get("instance_type_id"))
            print("Region:", offer.get("region"))
            print("Contract:", offer.get("contract"))

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

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

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python nova_offers.py

Windows PowerShell

PowerShell

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

To retrieve Spot offers, set offer_type="spot" in the function call. To retrieve On-Demand offers, omit the argument or use offer_type="on-demand".

Example Success Response

A successful request returns a JSON object containing the total number of offers, a descriptive message, an array of offer configurations, and the response status.

HTTP Status: 200 OK

On-Demand Offers

JSON

{
  "count": 19,
  "message": "Live Nova GPU offers retrieved successfully.",
  "offers": [
    {
      "contract": "on-demand",
      "display_name": "1x A100",
      "gpu_count": 1,
      "gpu_model": "A100",
      "instance_type_id": "1A100.22V",
      "region": "FIN-03"
    },
    {
      "contract": "on-demand",
      "display_name": "1x B200",
      "gpu_count": 1,
      "gpu_model": "B200",
      "instance_type_id": "1B200.30V",
      "region": "FIN-03"
    }
  ],
  "status": "success"
}

The example is abbreviated to show two offers from the sample response. The actual response may contain additional entries, and count represents the total number of offers returned.

Spot Offers

When the request uses type=spot, the returned offers have the spot contract type.

JSON

{
  "count": 16,
  "message": "Live Nova GPU offers retrieved successfully.",
  "offers": [
    {
      "contract": "spot",
      "display_name": "1x A100",
      "gpu_count": 1,
      "gpu_model": "A100",
      "instance_type_id": "1A100.22V",
      "region": "FIN-01"
    },
    {
      "contract": "spot",
      "display_name": "1x B300",
      "gpu_count": 1,
      "gpu_model": "B300",
      "instance_type_id": "1B300.30V",
      "region": "FIN-03"
    }
  ],
  "status": "success"
}

This example is also abbreviated for readability,The offer count and available configurations may differ when the endpoint is called in real time.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
count	Integer	The total number of offer entries returned by the API.
message	String	A descriptive message about the result of the request.
offers	Array of objects	Contains the available GPU instance offers matching the selected contract type.
offers[].contract	String	The pricing contract type, such as on-demand or spot.
offers[].display_name	String	The human-readable name of the GPU configuration, such as 1x A100.
offers[].gpu_count	Integer	The number of GPUs included in the configuration.
offers[].gpu_model	String	The GPU model associated with the offer, such as A100, H100, or B200.
offers[].instance_type_id	String	The identifier of the instance configuration.
offers[].region	String	The region code associated with the offer, such as FIN-03.

Understanding Nova GPU Offers

Each object in the offers array represents an available GPU instance configuration.

For example:

JSON

{
  "contract": "on-demand",
  "display_name": "1x H100",
  "gpu_count": 1,
  "gpu_model": "H100",
  "instance_type_id": "1H100.80S.32V",
  "region": "FIN-03"
}

This entry identifies an On-Demand configuration with one H100 GPU in region FIN-03.

Use the fields as follows:

• display_name identifies the configuration for display in your application.
• gpu_model identifies the GPU model.
• gpu_count indicates the number of GPUs in the configuration.
• instance_type_id identifies configuration for use in appropriate instance provisioning workflow.
• region identifies the region associated with the offer.
• contract identifies whether the offer is On-Demand or Spot.

Important Notes

1. Default Offer Type: If the type parameter is omitted, the endpoint returns On-Demand offers.

2. Spot Offers: To retrieve Spot offers, specify type=spot. Check the returned contract field when processing or displaying results.

3. Available Configurations: The offers and their regions may change. Retrieve the latest results before selecting a configuration for an instance launch.

4. Instance Type ID: Keep the returned instance_type_id exactly as provided when using it in a compatible Nova provisioning workflow.

5. Region Selection: Ensure that the selected offer's region is appropriate for your intended deployment.

6. Pricing Information: This endpoint's example response provides configuration and contract details but does not include a price field. Do not infer an hourly price from the display_name or instance_type_id.

Error Handling

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

Your application should handle authentication failures, invalid query values, network errors, request timeouts, server errors, and unexpected response formats. The exact error codes and response 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 GPU offers or API integration, contact the Dataoorts support team at [email protected].