Get usage analytics via the xAI Management API

Pull historical API spend as time series over HTTP when finance dashboards, anomaly pages, or nightly jobs need the same consumption rollup Console Usage Explorer shows without exporting charts by hand. Official Billing Management documents POST /v1/billing/teams/{team_id}/usage on https://management-api.x.ai, authorized with a management key. The body wraps an analyticsRequest with a local-timezone timeRange, a timeUnit bucket, values to aggregate, optional groupBy, and optional filters. 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 time window expressed in the team's working timezone rather than raw UTC wall clocks. Docs note aggregation cannot rely on UTC alone, so startTime and endTime use YYYY-MM-DD HH:MM:SS with an IANA timezone such as America/Chicago or Etc/GMT. The documented request example sums field usd with AGGREGATION_SUM, buckets with TIME_UNIT_DAY, and groups by description. Neighboring spend jobs include Check prepaid credit balance via the xAI Management API, List invoices via the xAI Management API, and the click-through explorer in Explore API usage in the xAI Console. More API jobs live on the API hub.

Query daily USD spend

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. Post an analytics request for a closed local window. The example below mirrors the official sample: daily USD sums from 2025-10-01 through the end of 2025-10-07 in Etc/GMT, grouped by description:

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/usage" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2025-10-01 00:00:00",
        "endTime": "2025-10-07 23:59:59",
        "timezone": "Etc/GMT"
      },
      "timeUnit": "TIME_UNIT_DAY",
      "values": [
        {
          "name": "usd",
          "aggregation": "AGGREGATION_SUM"
        }
      ],
      "groupBy": [
        "description"
      ],
      "filters": []
    }
  }'

3. Read each timeSeries entry. group / groupLabels identify the series (for example a chat model description). dataPoints are dense across the requested range: every bucket has a UTC timestamp and a values array aligned with your requested aggregations. Sum the numeric points when you need a window total for a single group.

4. Treat limitReached: true as a partial answer. Official docs state the query hit a cardinality cap and returned only a subset, so label charts as incomplete and narrow groupBy, tighten filters, or shrink timeRange before you treat the series as exact.

Documented timeUnit values include TIME_UNIT_MONTH, TIME_UNIT_CALENDAR_WEEK, TIME_UNIT_DAY, TIME_UNIT_HOUR, TIME_UNIT_QUARTER_HOUR, TIME_UNIT_MINUTE, TIME_UNIT_SECOND, and TIME_UNIT_NONE (one bucket for the whole window). Aggregation enums on each value include sum, average, min/max, percentiles, count, and count-distinct; the docs warn that not every field supports every aggregation. Keep every call on https://management-api.x.ai. An inference API key against https://api.x.ai will not answer billing routes.

Use the series in ops

Feed daily USD series into the same spend sheet you already reconcile against prepaid balance and invoices so API and Console agree on anomalies. When a pager fires on sudden cost, compare the offending groupLabels description against recent model or key changes before you raise spending limits. Pair the analytics response with Preview a postpaid invoice via the xAI Management API when you need the in-progress cycle draft rather than historical buckets.

Pitfalls

Sending UTC ISO timestamps where the API expects local YYYY-MM-DD HH:MM:SS plus timezone skews buckets and invents empty days. Ignoring limitReached turns a truncated cardinality result into a false “spend dropped” story. Using an inference key or the wrong host returns auth errors that look like missing usage. Mixing SuperGrok consumer weekly pools on grok.com with these team Management analytics produces a ledger that never closes against Console Billing.