Skip to main content
GET
/
v1
/
account
/
balance
Account Balance
curl --request GET \
  --url https://api.stratus.run/v1/account/balance \
  --header 'Authorization: <authorization>'
{
  "balance": 123,
  "account_id": "<string>",
  "email": "<string>"
}

​
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

​
Authorization
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

​
balance
number
Current credit balance (floating point). This is the number of credits remaining in your account.
​
account_id
string
Your unique account identifier
​
email
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"

​
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

MetricValue
Latency~50-100ms
Rate Limit100 requests/minute per API key
Caching30s 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()

​
See Also

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.