List invoices via the xAI Management API

Pull a team's invoice history over HTTP when finance exports, monthly close, or incident review need the same invoice rows Console Billing shows without clicking through each cycle by hand. Official Billing Management documents GET /v1/billing/teams/{team_id}/invoices on https://management-api.x.ai, authorized with a management key. The response returns an invoices array with invoice ids and numbers, create time, charging status, line items, subtotal/tax/total in USD cents, and monthly cycle metadata including prepaid and credit fields. 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 optional query filters when you only need one cycle or a known invoice id set. Documented query parameters include billingCycle.year, billingCycle.month, since.year, since.month, and invoiceIds.invoiceIds. Amounts on lines and totals are USD cent strings, matching the rest of the billing API. Neighboring prepaid and limit jobs include Check prepaid credit balance via the xAI Management API, Top up prepaid credits via the xAI Management API, and Set postpaid spending limits via the xAI Management API. Console-side purchase context lives in Purchase prepaid credits on the xAI Console. More API jobs live on the API hub.

List invoices for the team

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. List invoices with no filters when you need the recent history the API returns by default:

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

3. Narrow to a billing cycle when monthly close only cares about one month. Example for February 2025:

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/invoices?billingCycle.year=2025&billingCycle.month=2" \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}"

4. For each invoice object, read invoiceId, invoiceNumber, createTime, and invoiceStatus (PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED, or INVALID in the documented enum). Walk lines for cluster, description, unit type, unit price, unit count, and line amount. Use subtotal, tax, and total for the rollup in USD cents. When present, invoicePdfAssetKeySuffix and monthly CSV suffixes identify artifacts tied to that invoice for internal retrieval flows documented by xAI processes.

5. When you need the in-progress postpaid picture before the cycle closes, call GET /v1/billing/teams/{team_id}/postpaid/invoice/preview for the current period's draft amounts and effectiveSpendingLimit rather than expecting an unfinalized month to appear as a settled invoice row.

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

Use invoices in ops

Export invoiceNumber, status, totals, and line descriptions into the same finance sheet you already reconcile against Console downloads so API and UI agree. After a Management prepaid top-up, match invoiceId / invoiceNumber on the prepaid balance changes rows to the invoice list when a charge is under dispute. Treat FAILED charger attempts inside chargerAttempts as payment-method problems to fix in Console before you assume usage itself is wrong.

Pitfalls

Comparing cent totals as floats without conversion creates false variance against finance systems that store dollars. Filtering with the wrong billingCycle.month (or mixing since and billingCycle without checking which you meant) returns an empty array that looks like missing billing rather than a bad query. Expecting the PDF or CSV asset key suffixes to be anonymously downloadable URLs without the rest of xAI's asset access path leads to broken automation. Mixing SuperGrok consumer receipts on grok.com with these team Management invoices produces a ledger that never closes. Calling the list endpoint with an inference key or the wrong host returns auth errors that look like “no invoices” instead of a clear configuration mistake.