Usage Analytics

Understand Your API Consumption

An invoice tells you how much you spent; this endpoint tells you why. That’s the difference between observing and acting: consumption breaks down by model, by period, and at your chosen granularity, letting you tie a spike to a specific model at a specific time.

Its syntax is richer than the rest of the Management API—three blocks of parameters to combine—but it boils down to three questions: over what period, at what granularity, and what measure. This lesson covers them in that order. It lets you analyze consumption by model, by period, and with different time granularities—essential data for optimizing costs and sizing your infrastructure.

Analysis Endpoint

Usage analysis happens via a POST request:

POST /v1/billing/teams/{teamId}/usage

Request Structure

{
  "analyticsRequest": {
    "timeRange": {
      "startTime": "2026-03-01 00:00:00",
      "endTime": "2026-04-01 00:00:00",
      "timezone": "UTC"
    },
    "timeUnit": "DAY",
    "values": [
      {"name": "tokens", "aggregation": "SUM"}
    ],
    "groupBy": ["model"]
  }
}

This request asks for the sum of tokens consumed per day, broken down by model, for March 2026 in UTC. Treat it as a template: in practice, you’ll only change three things from one report to another—the period, the time unit, and the metric—while the rest of the structure remains identical.

Request Parameters

timeRange

Defines the analysis period:

• startTime : start of the period (format YYYY-MM-DD HH:MM:SS)
• endTime : end of the period (same format)
• timezone : time zone for date interpretation (e.g., UTC, Europe/Paris)

timeUnit

The time granularity of the results. Available options are:

• MONTH : monthly aggregation
• CALENDAR_WEEK : calendar week aggregation
• DAY : daily aggregation
• HOUR : hourly aggregation
• QUARTER_HOUR : quarter-hour aggregation
• MINUTE : minute aggregation
• SECOND : second aggregation

Choose granularity based on the duration of the phenomenon you’re looking for, not the length of the analyzed period. A monthly report reads well in DAY; a ten-minute spike disappears completely at that scale and only shows up in QUARTER_HOUR. Going too low has a cost too—the volume of returned points grows quickly, and so does the noise.

values

The choice of aggregation function changes the question asked, and this is where percentiles deserve your attention. AVG on latency gives a reassuring average that no one actually experiences; P99 gives the wait time endured by your unluckiest users—the ones who complain. For cost, use SUM; for performance, use a percentile.

"values": [
  {"name": "tokens", "aggregation": "SUM"},
  {"name": "tokens", "aggregation": "AVG"},
  {"name": "latency", "aggregation": "P99"}
]

Available aggregation functions:

• SUM : total sum
• AVG : average
• MIN : minimum value
• MAX : maximum value
• P50 : median (50th percentile)
• P90 : 90th percentile
• P99 : 99th percentile
• COUNT : number of occurrences
• COUNT_DISTINCT : number of distinct values

groupBy

Breaks down results by dimension. Currently, grouping by model is available, letting you see separate consumption for each model (grok-4.20-0309-reasoning, grok-4.3, etc.).

Practical Examples

Daily Consumption for Current Month

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-04-01 00:00:00",
        "endTime": "2026-05-01 00:00:00",
        "timezone": "Europe/Paris"
      },
      "timeUnit": "DAY",
      "values": [{"name": "tokens", "aggregation": "SUM"}],
      "groupBy": ["model"]
    }
  }'

Number of Requests per Hour

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-04-03 00:00:00",
        "endTime": "2026-04-04 00:00:00",
        "timezone": "Europe/Paris"
      },
      "timeUnit": "HOUR",
      "values": [{"name": "requests", "aggregation": "COUNT"}],
      "groupBy": ["model"]
    }
  }'

P99 Latency by Model

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-04-01 00:00:00",
        "endTime": "2026-04-04 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "DAY",
      "values": [
        {"name": "latency", "aggregation": "P99"},
        {"name": "latency", "aggregation": "AVG"}
      ],
      "groupBy": ["model"]
    }
  }'

Key Takeaways

• The POST /v1/billing/teams/{teamId}/usage endpoint centralizes all analytics
• 7 time granularities available, from SECOND to MONTH
• 9 aggregation functions: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
• The groupBy: ["model"] parameter breaks down results by model
• Use the Europe/Paris time zone for reports aligned with your working hours