176 176
177 * `unitType` (string) — The unit in which the price is measured.177 * `unitType` (string) — The unit in which the price is measured.
178 178
179 * `unitPrice` (string) — The price per unit (1/1\_000\_000 USD cents).179 * `unitPrice` (string) — The price per unit in ticks of 1e-10 USD (1/100\_000\_000 USD cents).
180 180
181 * `numUnits` (string) — The number of units.181 * `numUnits` (string) — The number of units.
182 182
450 450
451 * `unitType` (string) — The unit in which the price is measured.451 * `unitType` (string) — The unit in which the price is measured.
452 452
453 * `unitPrice` (string) — The price per unit (1/1\_000\_000 USD cents).453 * `unitPrice` (string) — The price per unit in ticks of 1e-10 USD (1/100\_000\_000 USD cents).
454 454
455 * `numUnits` (string) — The number of units.455 * `numUnits` (string) — The number of units.
456 456
802 802
803***803***
804 804
805## Daily token usage
806
807`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](/console/usage). Authenticate with a management key.
808
809Choose what to measure with `values[].name`. Each value supports only `AGGREGATION_SUM`.
810
811| Value | Measures |
812| --- | --- |
813| `usd` | Cost in USD |
814| `units` | Tokens for token unit types; other units, such as images or audio seconds, for the rest |
815| `items` | Billing items; one request produces an item for each priced dimension |
816| `transactions` | Requests |
817
818You 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.
819
820The following request returns daily token counts for each token type and model:
821
822```bash
823curl https://management-api.x.ai/v1/billing/teams/{team_id}/usage \
824 -X POST \
825 -H "Authorization: Bearer $XAI_MANAGEMENT_KEY" \
826 -H "Content-Type: application/json" \
827 -d '{
828 "analyticsRequest": {
829 "timeRange": {
830 "startTime": "2026-10-26 00:00:00",
831 "endTime": "2026-11-03 00:00:00",
832 "timezone": "Etc/GMT"
833 },
834 "timeUnit": "TIME_UNIT_DAY",
835 "values": [{ "name": "units", "aggregation": "AGGREGATION_SUM" }],
836 "groupBy": ["unit_type", "description"],
837 "filters": []
838 }
839 }'
840```
841
842The 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.
843
844* `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.
845* Keep `unit_type` in `groupBy` when you measure `units`. Grouping by `description` alone adds every unit type for a model into one number.
846* If `limitReached` is `true`, the response hit its row limit and may be incomplete; shorten the time range or group by fewer fields.
847* An unknown value or field name returns HTTP 400.
848
849### Split long- vs short-context tokens
850
851Long-context requests are billed at higher rates (see [Pricing](/developers/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:
852
853```json
854"groupBy": ["unit_type", "description", "unit_price"]
855```
856
857`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](/developers/advanced-api-usage/regions) 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"]`.
858
859***
860
805## POST /v1/billing/teams/\{team\_id}/usage861## POST /v1/billing/teams/\{team\_id}/usage
806 862
807Get historical usage of the API over a time period, aggregated by fields.863Get historical usage of the API (spend, token and other unit counts) over a time period,
864bucketed by time and grouped by fields. For daily token counts, sum \`units\` per day grouped by
865\`unit\_type\`.
808 866
809### Path Parameters867### Path Parameters
810 868
831 889
832 * `values` (array\<object>) — Name of the fields to aggregate.890 * `values` (array\<object>) — Name of the fields to aggregate.
833 891
834 * `name` (string) — Name of the field to measure.892 * `name` (string) — Name of the value to measure. Valid names, and the aggregations each one supports, depend on
893 the endpoint; see the endpoint's request description.
835 894
836 * `aggregation` ("AGGREGATION\_NONE" | "AGGREGATION\_SUM" | "AGGREGATION\_AVG" | "AGGREGATION\_VAR" | "AGGREGATION\_STD" | "AGGREGATION\_MIN" | "AGGREGATION\_MAX" | "AGGREGATION\_P50" | "AGGREGATION\_P90" | "AGGREGATION\_P99" | "AGGREGATION\_P999" | "AGGREGATION\_COUNT" | "AGGREGATION\_COUNT\_DISTINCT") — Each value is an aggregate of the individual values in the time bucket. Note that not every field895 * `aggregation` ("AGGREGATION\_NONE" | "AGGREGATION\_SUM" | "AGGREGATION\_AVG" | "AGGREGATION\_VAR" | "AGGREGATION\_STD" | "AGGREGATION\_MIN" | "AGGREGATION\_MAX" | "AGGREGATION\_P50" | "AGGREGATION\_P90" | "AGGREGATION\_P99" | "AGGREGATION\_P999" | "AGGREGATION\_COUNT" | "AGGREGATION\_COUNT\_DISTINCT") — Each value is an aggregate of the individual values in the time bucket. Note that not every field
837 supports every aggregation method.896 supports every aggregation method.
865 "analyticsRequest": {924 "analyticsRequest": {
866 "timeRange": {925 "timeRange": {
867 "startTime": "2025-10-01 00:00:00",926 "startTime": "2025-10-01 00:00:00",
868 "endTime": "2025-10-07 23:59:59",927 "endTime": "2025-10-08 00:00:00",
869 "timezone": "Etc/GMT"928 "timezone": "Etc/GMT"
870 },929 },
871 "timeUnit": "TIME_UNIT_DAY",930 "timeUnit": "TIME_UNIT_DAY",
872 "values": [931 "values": [
873 {932 {
874 "name": "usd",933 "name": "units",
875 "aggregation": "AGGREGATION_SUM"934 "aggregation": "AGGREGATION_SUM"
876 }935 }
877 ],936 ],
878 "groupBy": [937 "groupBy": [
938 "unit_type",
879 "description"939 "description"
880 ],940 ],
881 "filters": []941 "filters": []
