Billing Management

POST /v1/billing/teams/{team_id}/usage returns your team's usage as time series, bucketed by time and optionally grouped by fields such as token type and model. It reads the same data as Usage Explorer. Authenticate with a management key.

Choose what to measure with values[].name. Each value supports only AGGREGATION_SUM.

You can group and filter by unit_type, description, api_key_id, product, request_ip, user_id, and unit_price. unit_type is the token type, such as Prompt text tokens, Cached prompt text tokens, Completion text tokens, or Reasoning text tokens. Prompt text tokens counts only uncached input; cached input is reported as Cached prompt text tokens. description is the product name followed by the billed resource, usually the model.

The following request returns daily token counts for each token type and model:

curl https://management-api.x.ai/v1/billing/teams/{team_id}/usage \
  -X POST \
  -H "Authorization: Bearer $XAI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "analyticsRequest": {
          "timeRange": {
            "startTime": "2026-10-26 00:00:00",
            "endTime": "2026-11-03 00:00:00",
            "timezone": "Etc/GMT"
          },
          "timeUnit": "TIME_UNIT_DAY",
          "values": [{ "name": "units", "aggregation": "AGGREGATION_SUM" }],
          "groupBy": ["unit_type", "description"],
          "filters": []
        }
      }'

The response has one entry in timeSeries for each combination of group values. Its group array lists those values in groupBy order, so here the token type comes first and the description second. dataPoints has one entry per day in the range, and values[0] holds that day's token count.

• startTime and endTime use the format YYYY-MM-DD HH:MM:SS in the IANA time zone given by timezone, which also sets the day boundaries. endTime is exclusive.
• Keep unit_type in groupBy when you measure units. Grouping by description alone adds every unit type for a model into one number.
• If limitReached is true, the response hit its row limit and may be incomplete; shorten the time range or group by fewer fields.
• An unknown value or field name returns HTTP 400.

Long-context requests are billed at higher rates (see Pricing), but their tokens are reported under the same unit_type and description as other tokens. To separate them, add unit_price to groupBy in the request above so that each price gets its own time series:

"groupBy": ["unit_type", "description", "unit_price"]

unit_price is measured in 1e-10 USD per unit, so dividing it by 10,000 gives USD per million tokens; "25000" is $2.50 per million tokens. Match each series to the model's standard and long-context rates to tell them apart. A token type and model can have other series too, for example from US regional endpoint rates, custom pricing, or a price change during the time range. To return only some prices, filter on unit_price, e.g., "filters": ["unit_price:>12500"].