Prepaid Credits — Management API: Keys & Billing

xAI prepaid model

Prepaid credits let you purchase a balance upfront, consumed as you make API calls. This model is ideal for controlling spending: you only spend what you bought, with no end-of-month surprises. Credits are used before monthly billing.

Check your balance

Prepaid flips the risk relationship compared to monthly billing. With postpaid, you discover the amount at the end; with prepaid, the cap is set in advance and the worst-case scenario is service interruption—unpleasant, but bounded. For a team exploring the API or a project with a fixed budget, this is the right trade-off.

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

The response contains:

The current balance in dollars
The top-up history with dates and amounts
The usage history by period

Buy credits (top-up)

To recharge your credit balance:

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/top-up" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00
  }'

Important points about credits

The four points below have concrete consequences for how you automate. The second one especially: credits are non-refundable. This alone rules out the strategy of a single large purchase “to be safe”—modest, frequent top-ups are better, even if you automate them, than capital tied up in a project that might change direction.

Credits are charged immediately at purchase on your default payment method
Prepaid credits are non-refundable (unless legally required in your jurisdiction)
Credits are consumed in priority before monthly postpaid billing
There is no expiration date listed for credits—they remain available until consumed

Billing flow with credits

It’s worth knowing the consumption order before configuring anything, as it determines what each of your dashboards shows. Credits go first, monthly billing takes over afterward: in other words, a prepaid balance stagnating at zero while everything works means you’ve already switched to postpaid without realizing it.

Prepaid credits available: tokens are deducted from the prepaid balance
Credits exhausted: consumption switches to monthly billing (postpaid)
Spending limit reached: requests are refused

Credit usage strategies

Fixed monthly budget

This is the hard budget strategy: without monthly billing enabled, exhausting credits stops calls instead of generating debt. Accept the trade-off—service interrupts, and it’s better that this be an explicit choice than a Friday evening discovery. Combine it with the low balance alert described later.

import requests
from datetime import datetime

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Check balance
balance_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
balance = balance_resp.json().get("balance", 0)

# Recharge if balance is low
MONTHLY_BUDGET = 200.00
RECHARGE_THRESHOLD = 50.00

if balance < RECHARGE_THRESHOLD:
    top_up_amount = MONTHLY_BUDGET - balance
    requests.post(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/top-up",
        headers={
            "Authorization": f"Bearer {MGMT_KEY}",
            "Content-Type": "application/json"
        },
        json={"amount": top_up_amount}
    )
    print(f"Recharged ${top_up_amount:.2f}")

Project provisioning

Project provisioning has an advantage beyond accounting: the balance becomes a progress measure. If half the credits are consumed while a quarter of the work is done, you get the information before the end, when there’s still time to decide whether to reduce scope or switch models.

# Project budget: $500 over 3 months
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/top-up" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500.00}'

Then monitor usage via analytics (next lesson) to ensure the budget is respected.

Balance monitoring

Low balance alert

#!/bin/bash
BALANCE=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('balance', 0))")

THRESHOLD=20.00
if (( $(echo "$BALANCE < $THRESHOLD" | bc -l) )); then
    echo "ALERT: low prepaid balance ($BALANCE $)"
    # Send a notification
fi

Usage dashboard

Combine the prepaid balance with the postpaid charge preview for a complete view of your costs:

# Prepaid balance
echo "=== Prepaid Credits ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

# Current postpaid charges
echo "=== Postpaid Charges ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

Key takeaways

GET /v1/billing/teams/{teamId}/prepaid/balance returns the balance and history
POST /v1/billing/teams/{teamId}/prepaid/top-up buys credits (charged immediately)
Prepaid credits are non-refundable
Credits are consumed before monthly billing
Automate top-ups with a minimum threshold to avoid interruptions
Combine prepaid credits and spending limits for total cost control