Check prepaid credit balance via the xAI Management API

Read an xAI team's prepaid credit balance and recent balance changes over HTTP when dashboards, cron jobs, or paging need the same numbers the Console shows under Billing. Official Billing Management documents GET /v1/billing/teams/{team_id}/prepaid/balance on https://management-api.x.ai, authorized with a management key. The response includes a total amount in USD cents and a changes array whose origins include PURCHASE, SPEND, REFUND, MANUAL, and AUTO_PURCHASE. Create the management key first with Create a management key in the xAI Console if you do not already have one.

What you need

A management key that can call billing routes for the team, the team id in the path, and a client that can send HTTPS GET with Authorization: Bearer. Amounts in this API are represented as USD cents string values inside objects such as {"val": "1000"}, so convert carefully before you alert on dollars. For the click-through purchase and auto-refill path that creates many of those change rows, use Purchase prepaid credits on the xAI Console and Set auto top-up on the xAI Console. Neighboring admin pulls include List audit events via the xAI Management API and Manage API keys with the xAI Management API. More API jobs live on the API hub.

Call the prepaid balance endpoint

1. Export the management key and team id outside of source control:

export XAI_MANAGEMENT_KEY="your_management_key"
export XAI_TEAM_ID="your_team_id"

2. Request the prepaid balance and change history:

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/prepaid/balance" \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}"

3. Read total.val as the current prepaid balance in USD cents. Walk changes when you need the audit trail of purchases, spend, refunds, staff adjustments, and automatic top-ups. Each change can include changeOrigin, topupStatus, amount, invoice identifiers, timestamps, and a paymentProcessor object when a charge was involved.

4. Map origins to the story you expect. PURCHASE and AUTO_PURCHASE amounts are negative in the documented sense for credits added through checkout; SPEND amounts are positive as usage deducts from the pool; REFUND and MANUAL follow the signs described in the billing reference. Use topupStatus values such as SUCCEEDED, TO_CHARGE, or FAILED_TO_CHARGE when you are debugging a top-up that has not landed yet.

Keep the call on https://management-api.x.ai. An inference API key against https://api.x.ai will not answer this route.

Use the balance in ops

Alert when total.val crosses the same floor you configured for Console auto top-up so humans and automation agree. After a manual Guest Checkout purchase, poll until a new PURCHASE row appears with topupStatus of SUCCEEDED, remembering that bank transfers can take two to three business days before credits grant. When you also top up programmatically, the sibling Management API route is POST /v1/billing/teams/{team_id}/prepaid/top-up with an amount.val in USD cents against the default payment method — still confirm the resulting change row before you declare the pool healthy.

Pitfalls

Comparing cent strings as floats without conversion creates false alarms around tiny balances. Watching only total and ignoring FAILED_TO_CHARGE rows hides payment-method problems until traffic dies. Calling the endpoint with an inference key or the wrong host returns auth errors that look like empty billing data. Mixing this prepaid team pool with SuperGrok consumer weekly usage on grok.com produces dashboards that never match Console Billing. Assuming a just-submitted bank transfer already increased total contradicts the Console billing note that credits arrive only after processing completes.