Account Balance

Overview

The /v1/account/balance endpoint retrieves your current credit balance and account information. Use this to check remaining credits before making API calls or to display balance in your application.

Authentication required - This endpoint requires a valid Stratus API key in the Authorization header.

Use Cases

Balance Monitoring

Check remaining credits before expensive operations

UI Display

Show real-time balance in your application dashboard

Budget Alerts

Trigger notifications when balance drops below threshold

Usage Tracking

Track credit consumption over time

Request

GET https://api.stratus.run/v1/account/balance

Headers

string

required

Your Stratus API key. Format: Bearer stratus_sk_live_... or just stratus_sk_live_...

No request body or query parameters required.

Response

{
  "balance": 1234.56,
  "account_id": "acc_a1b2c3d4e5f6",
  "email": "user@example.com"
}

Response Fields

number

Current credit balance (floating point). This is the number of credits remaining in your account.

string

Your unique account identifier

string

Email address associated with your account

Examples

Check Current Balance

curl https://api.stratus.run/v1/account/balance \
  -H "Authorization: Bearer $STRATUS_API_KEY"

const response = await fetch('https://api.stratus.run/v1/account/balance', {
  headers: {
    'Authorization': `Bearer ${process.env.STRATUS_API_KEY}`
  }
});

const data = await response.json();
console.log(`Balance: ${data.balance} credits`);

import requests
import os

response = requests.get(
    "https://api.stratus.run/v1/account/balance",
    headers={
        "Authorization": f"Bearer {os.environ['STRATUS_API_KEY']}"
    }
)

data = response.json()
print(f"Balance: {data['balance']} credits")

Display Balance in UI

async function getAccountBalance(): Promise<number> {
  const response = await fetch('https://api.stratus.run/v1/account/balance', {
    headers: {
      'Authorization': `Bearer ${process.env.STRATUS_API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch balance: ${response.statusText}`);
  }

  const data = await response.json();
  return data.balance;
}

// Usage in React component
function DashboardHeader() {
  const [balance, setBalance] = useState<number>(0);

  useEffect(() => {
    getAccountBalance().then(setBalance);
  }, []);

  return (
    <div>
      <h2>Credits Remaining: {balance.toFixed(2)}</h2>
    </div>
  );
}

Balance Check Before Request

def make_request_with_balance_check(prompt: str, min_credits: float = 10.0):
    """Make API request only if sufficient credits available"""

    # Check balance first
    balance_response = requests.get(
        "https://api.stratus.run/v1/account/balance",
        headers={"Authorization": f"Bearer {os.environ['STRATUS_API_KEY']}"}
    )
    balance_data = balance_response.json()

    if balance_data['balance'] < min_credits:
        raise Exception(f"Insufficient credits: {balance_data['balance']} < {min_credits}")

    # Proceed with request
    response = requests.post(
        "https://api.stratus.run/v1/chat/completions",
        headers={"Authorization": f"Bearer {os.environ['STRATUS_API_KEY']}"},
        json={
            "model": "stratus-x1ac-base-gpt-4o",
            "messages": [{"role": "user", "content": prompt}]
        }
    )

    return response.json()

Low Balance Alert

async function checkBalanceAndAlert(threshold: number = 100) {
  const response = await fetch('https://api.stratus.run/v1/account/balance', {
    headers: {
      'Authorization': `Bearer ${process.env.STRATUS_API_KEY}`
    }
  });

  const data = await response.json();

  if (data.balance < threshold) {
    // Send alert (email, Slack, etc.)
    await sendAlert({
      subject: 'Low Stratus Credits',
      message: `Balance is low: ${data.balance} credits remaining`,
      accountId: data.account_id,
      email: data.email
    });
  }

  return data.balance;
}

// Run periodically
setInterval(() => checkBalanceAndAlert(100), 3600000); // Every hour

Error Responses

401 Unauthorized

Missing or invalid API key:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Solution: Ensure you’re passing a valid Stratus API key in the Authorization header.

503 Service Unavailable

Billing service temporarily unavailable:

{
  "error": {
    "message": "Billing service unavailable",
    "type": "service_error",
    "code": "billing_unavailable"
  }
}

Solution: Retry after a short delay. If the issue persists, check the health endpoint for system status.

Performance

Metric	Value
Latency	~50-100ms
Rate Limit	100 requests/minute per API key
Caching	30s recommended (balance updates in real-time)

Balance updates are reflected immediately after API calls or credit purchases. For UI display, cache for 30-60 seconds to reduce API calls.

Best Practices

Cache Wisely

Cache balance for 30-60 seconds in your application to avoid excessive API calls

Check Before Large Operations

Verify sufficient credits before batching multiple requests

Set Alert Thresholds

Implement low-balance alerts to avoid service interruption

Display in Dashboard

Show balance prominently in your app’s UI for user awareness

Integration Patterns

Middleware for Balance Checking

// Express middleware example
async function checkBalanceMiddleware(req, res, next) {
  try {
    const response = await fetch('https://api.stratus.run/v1/account/balance', {
      headers: {
        'Authorization': req.headers.authorization
      }
    });

    const data = await response.json();

    // Attach balance to request
    req.stratusBalance = data.balance;

    // Block if balance too low
    if (data.balance < 1) {
      return res.status(402).json({
        error: 'Insufficient credits',
        balance: data.balance
      });
    }

    next();
  } catch (error) {
    next(error);
  }
}

// Use in routes
app.post('/api/chat', checkBalanceMiddleware, handleChatRequest);

Background Balance Monitoring

import time
import threading

class BalanceMonitor:
    def __init__(self, api_key: str, check_interval: int = 300):
        self.api_key = api_key
        self.check_interval = check_interval  # seconds
        self.current_balance = 0.0
        self.running = False

    def start(self):
        self.running = True
        thread = threading.Thread(target=self._monitor_loop)
        thread.daemon = True
        thread.start()

    def stop(self):
        self.running = False

    def _monitor_loop(self):
        while self.running:
            try:
                response = requests.get(
                    "https://api.stratus.run/v1/account/balance",
                    headers={"Authorization": f"Bearer {self.api_key}"}
                )
                data = response.json()
                self.current_balance = data['balance']

                # Check threshold
                if self.current_balance < 50:
                    self._send_low_balance_alert(self.current_balance)

            except Exception as e:
                print(f"Balance check failed: {e}")

            time.sleep(self.check_interval)

    def _send_low_balance_alert(self, balance: float):
        # Implement your alert logic (email, Slack, etc.)
        print(f"⚠️  Low balance alert: {balance} credits")

# Usage
monitor = BalanceMonitor(api_key=os.environ['STRATUS_API_KEY'], check_interval=300)
monitor.start()

Chat Completions - Make inference requests (consumes credits)
Messages - Anthropic-compatible endpoint (consumes credits)
Health Check - Check overall API status

Pro Tip

Implement a balance cache with 30-60 second TTL in your application. This provides real-time balance visibility while minimizing API calls to the balance endpoint.

API Reference

Overview

Use Cases

Balance Monitoring

UI Display

Budget Alerts

Usage Tracking

Request

Headers

Response

Response Fields

Examples

Check Current Balance

Display Balance in UI

Balance Check Before Request

Low Balance Alert

Error Responses

401 Unauthorized

503 Service Unavailable

Performance

Best Practices

Cache Wisely

Check Before Large Operations

Set Alert Thresholds

Display in Dashboard

Integration Patterns

Middleware for Balance Checking

Background Balance Monitoring

See Also

Pro Tip

​Overview

​Use Cases

Balance Monitoring

UI Display

Budget Alerts

Usage Tracking

​Request

​Headers

​Response

​Response Fields

​Examples

​Check Current Balance

​Display Balance in UI

​Balance Check Before Request

​Low Balance Alert

​Error Responses

​401 Unauthorized

​503 Service Unavailable

​Performance

​Best Practices

Cache Wisely

Check Before Large Operations

Set Alert Thresholds

Display in Dashboard

​Integration Patterns

​Middleware for Balance Checking

​Background Balance Monitoring

​Related Endpoints

​See Also

Pro Tip

Overview

Use Cases

Request

Headers

Response

Response Fields

Examples

Check Current Balance

Display Balance in UI

Balance Check Before Request

Low Balance Alert

Error Responses

401 Unauthorized

503 Service Unavailable

Performance

Best Practices

Integration Patterns

Middleware for Balance Checking

Background Balance Monitoring

Related Endpoints

See Also