Set postpaid spending limits via the xAI Management API

Read and update a team's postpaid monthly soft spending limit over HTTP when finance or platform ops need a hard ceiling on accrued postpaid usage after prepaid credits are exhausted. Official Billing Management documents GET and POST /v1/billing/teams/{team_id}/postpaid/spending-limits on https://management-api.x.ai, authorized with a management key. The GET response returns soft and hard limit objects in USD cents; the POST accepts desiredSoftSpendingLimit.val as a cent string and returns the soft limit applied for the billing period. Docs note that prepaid credits are always consumed before postpaid usage accrues, and setting the soft limit to 0 confines the team to prepaid-only spend. 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 agreement on the soft limit in USD cents (for example "20000" for two hundred dollars). Understand that this soft limit does not cap prepaid credit burn — only postpaid accrual after the prepaid pool is empty. When the team has consumed prepaid credits and postpaid usage reaches the soft spending limit, the API stops functioning per the billing reference. Neighboring prepaid jobs include Check prepaid credit balance via the xAI Management API and Top up prepaid credits via the xAI Management API. Console purchase and auto-refill remain Purchase prepaid credits on the xAI Console and Set auto top-up on the xAI Console. More API jobs live on the API hub.

Read the current limits

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. Fetch the postpaid spending-limits object:

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

3. Read the nested spendingLimits fields. Documented shapes include softSl, effectiveSl, hardSlAuto, effectiveHardSl, and optional hard overrides, each as {"val": "..."} USD cent strings. Use effectiveSl when you need the soft ceiling that actually gates traffic, and compare it to finance policy before you change anything.

4. Optionally preview the current billing period's postpaid exposure with GET /v1/billing/teams/{team_id}/postpaid/invoice/preview, which returns an effectiveSpendingLimit alongside the in-progress invoice amounts so you can see how close the team is to the ceiling.

Set the soft spending limit

1. POST the desired soft limit in USD cents. The example below sets two hundred dollars (20000 cents):

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/postpaid/spending-limits" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "desiredSoftSpendingLimit": {
      "val": "20000"
    }
  }'

2. Confirm the response thisBpSoftSpendingLimit.val matches what you sent, then re-GET the spending-limits resource so effectiveSl reflects the new policy for monitors and tickets.

3. To run prepaid-only for the period, set desiredSoftSpendingLimit.val to "0". Prepaid credits continue to spend normally; postpaid accrual is blocked once prepaid is exhausted, which is the documented way to refuse postpaid overrun.

Keep every call on https://management-api.x.ai. An inference API key against https://api.x.ai will not answer billing routes.

Pitfalls

Treating the soft limit as a prepaid cap contradicts the billing reference: prepaid always burns first and is not restricted by this endpoint. Sending dollar amounts without converting to cents ("200" when you meant two hundred dollars) sets a two-dollar ceiling and trips production almost immediately. Raising the soft limit without watching prepaid balance can still surprise finance when prepaid runs out and postpaid starts accruing up to the new ceiling. Confusing this xAI Management route with Cursor Admin spend-limit APIs produces scripts aimed at the wrong host and auth model. Assuming the API keeps serving after prepaid is empty and the soft limit is reached ignores the documented stop behavior and turns a billing control into an unexpected outage.