Account Balance

This endpoint retrieves the authenticated user's real-time Dataoorts account balance, currency, recharge thresholds, and instance launch eligibility. It is used to monitor account funds and verify available balance before triggering automated instance deployments.

Get Real-Time Account Balance

Retrieve the authenticated user's current account balance and related account status information using the Dataoorts Balance API.

This endpoint returns a JSON response containing the available account balance, account currency, balance threshold, instance launch eligibility, and minimum recharge amount. You can use this information to monitor account funds, determine whether an instance can be launched, and build account balance checks into your applications or automation workflows.

Endpoint

Property	Value
HTTP Method	GET
Endpoint	/balance
Base URL	https://cloud.dataoorts.com/api/v1
Full URL	https://cloud.dataoorts.com/api/v1/balance
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 from the Dataoorts Unify API.

Keep your API key confidential, Do not hardcode it into public repos or expose it in client-side applications.

Request Examples

Use the following command to retrieve your account balance:

Bash

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

Replace YOUR_API_KEY with your actual Dataoorts API key.

For production environments, store the API key in an environment variable instead of embedding it directly in your command or application.

---

The following example uses the requests library to fetch and parse the account balance response.

Python

import os
import requests


API_BASE_URL = "https://cloud.dataoorts.com/api/v1"


def get_account_balance(api_key: str) -> dict:
    """
    Retrieve the current Dataoorts account balance.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response returned by the API.

    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.
    """
    url = f"{API_BASE_URL}/balance"

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

    response = requests.get(
        url,
        headers=headers,
        timeout=10,
    )

    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Please set the DATAOORTS_API_KEY environment variable."
        )

    try:
        account = get_account_balance(api_key)

        print("Account Balance:", account.get("balance"))
        print("Currency:", account.get("currency"))
        print("Can Launch Instance:", account.get("can_launch_instance"))

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

    except ValueError as exc:
        print(f"Invalid JSON response: {exc}")

Set the DATAOORTS_API_KEY environment variable before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python balance.py

Windows PowerShell

PowerShell

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

Example Json Response

A successful request returns a JSON response similar to the following:

JSON

{
  "status": "success",
  "balance": 25.4860,
  "currency": "USD",
  "threshold_balance": 0.79,
  "can_launch_instance": true,
  "minimum_recharge_amount": 4.99
}

Response Fields

Field	Type	Description
status	string	Indicates the result of the API request. A successful response returns success.
balance	number	The current account balance.
currency	string	The currency used for the account balance, such as USD.
threshold_balance	number	The account's balance threshold value returned by the API.
can_launch_instance	boolean	Indicates whether the account is currently eligible to launch an instance.
minimum_recharge_amount	number	The minimum amount required or accepted for an account recharge.

Understanding Instance Launch Eligibility

The can_launch_instance field provides a convenient way to check whether the account is currently eligible to launch an instance.

• true — The account is currently eligible to launch an instance.
• false — The account is currently not eligible to launch an instance.

Use this field as an account eligibility check before initiating an instance launch workflow. The actual launch operation may still be subject to other requirements, including resource availability, account permissions, and service-specific restrictions.

Error Handling

An API request may fail because of an authentication issue, an HTTP error, a network failure, or an unexpected response.

When integrating this endpoint, handle errors by checking the HTTP status code and parsing the response body where appropriate. In Python, response.raise_for_status() raises an exception when the server returns an unsuccessful HTTP status code.

Do not assume that error responses contain the same fields as the successful response shown above.