/v1/billing/teams/{team_id}/billing-info

Get billing information of the team with given team ID.

Path Parameters

team_idstring

Team ID of the team.

Response Body

billingInfoobject

Billing info.

No parameters.

{
  "billingInfo": {
    "name": "Acme Inc.",
    "address": {
      "line1": "123 Main St.",
      "line2": "",
      "city": "New York",
      "country": "US",
      "postalCode": "12345",
      "state": "New York"
    },
    "email": "foo@example.com",
    "taxIdType": "us_ein",
    "taxNumber": "12-3456789"
  }
}

Set billing information

/v1/billing/teams/{team_id}/billing-info

Set billing information of a team.

Path Parameters

team_idstring

Team ID of the team.

Request Body

{
  "billingInfo": {
    "name": "Acme Inc.",
    "address": {
      "line1": "123 Main St.",
      "line2": "",
      "city": "New York",
      "country": "US",
      "postalCode": "12345",
      "state": "New York"
    },
    "email": "foo@example.com",
    "taxIdType": "us_ein",
    "taxNumber": "12-3456789"
  }
}

{}

List Invoices

/v1/billing/teams/{team_id}/invoices

List invoices that belong to a team.

Path Parameters

team_idstring

Team ID of the team.

Query Parameters

billingCycle.yearinteger

billingCycle.monthinteger

since.yearinteger

since.monthinteger

invoiceIds.invoiceIdsarray<string>

Response Body

invoicesarray<object>

Invoices.

No parameters.

{
  "invoices": [
    {
      "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
      "invoiceId": "aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=",
      "invoiceNumber": "742-250-927-721",
      "createTime": "2025-04-01T21:19:48.569466Z",
      "invoiceStatus": "PAID",
      "firstDesiredNextCycleTs": "2025-04-11T02:46:58Z",
      "chargerAttempts": [
        {
          "ticket": 0,
          "successful": false,
          "paymentMethodId": ""
        },
        {
          "ticket": 1,
          "successful": true,
          "paymentMethodId": ""
        }
      ],
      "lines": [
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Prompt text tokens",
          "unitPrice": "20000",
          "numUnits": "908",
          "amount": "0"
        },
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Completion text tokens",
          "unitPrice": "100000",
          "numUnits": "534",
          "amount": "0"
        }
      ],
      "subtotal": "0",
      "tax": "0",
      "total": "0",
      "invoicePdfAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=.pdf",
      "monthly": {
        "billingCycle": {
          "year": 2025,
          "month": 2
        },
        "defaultCreditsIssued": {
          "val": "0"
        },
        "autoCreditsIssued": {
          "val": "0"
        },
        "prepaidTokensToSpend": {
          "val": "0"
        },
        "billingItemsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-billing_items.csv.zstd",
        "correctionsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-corrections.csv.zstd"
      }
    }
  ]
}

List payment methods

/v1/billing/teams/{team_id}/payment-method

List payment methods of a team. You can add or delete the payment methods on https://console.x.ai.

Path Parameters

team_idstring

Team ID of the team.

Response Body

paymentMethodsarray<object>

Payment methods on file.

pendingPaymentMethodobject

Represents an incomplete attempt to add a payment method. Might resolve into a payment method.

No parameters.

{
  "paymentMethods": [
    {
      "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx",
      "billingInfo": {
        "name": "Acme Inc.",
        "address": {
          "line1": "123 Main St.",
          "line2": "",
          "city": "New York",
          "country": "US",
          "postalCode": "12345",
          "state": "New York"
        },
        "email": "foo@example.com",
        "taxIdType": "us-ein",
        "taxNumber": "123-3456789"
      },
      "cardDetails": {
        "brand": "mastercard",
        "expMonth": "12",
        "expYear": "2030",
        "last4": "4444"
      },
      "usBankAccountDetails": null,
      "linkDetails": null,
      "paymentType": "card"
    }
  ],
  "pendingPaymentMethod": null
}

Set default payment method

/v1/billing/teams/{team_id}/payment-method/default

Set default payment method to an existing payment method on file.

Path Parameters

team_idstring

Team ID of the team.

Request Body

{
  "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx"
}

{}

Preview postpaid invoice of the month

/v1/billing/teams/{team_id}/postpaid/invoice/preview

Preview the amount to pay for postpaid usage in the current billing period.

Path Parameters

team_idstring

Team ID of the team.

Response Body

coreInvoiceobject

The invoice object.

effectiveSpendingLimitstring

The effective current spending limit in USD cents.

defaultCreditsstring

The current default credits in USD cents.

billingCycleobject

No parameters.

{
  "coreInvoice": {
    "lines": [],
    "amountBeforeVat": "0",
    "vatCost": "0",
    "amountAfterVat": "0",
    "autoCreditsIssued": "0",
    "defaultCreditsIssued": "0",
    "totalWithCorr": {
      "val": "0"
    },
    "prepaidCredits": {
      "val": "-4500"
    },
    "prepaidCreditsUsed": {
      "val": "0"
    }
  },
  "effectiveSpendingLimit": "20000",
  "defaultCredits": "0",
  "billingCycle": {
    "year": 2025,
    "month": 11
  }
}

Get monthly postpaid spending limits

/v1/billing/teams/{team_id}/postpaid/spending-limits

Get the postpaid monthly spending limits. The API will stop functioning once the team has consumed all of the prepaid credits, and the postpaid usage amount has reached the user-set soft spending limit.

Path Parameters

team_idstring

Team ID of the team.

Response Body

spendingLimitsobject

Postpaid monthly spending limit.

No parameters.

{
  "spendingLimits": {
    "hardSlAuto": {
      "val": "22500"
    },
    "effectiveHardSl": {
      "val": "22500"
    },
    "softSl": {
      "val": "20000"
    },
    "effectiveSl": {
      "val": "20000"
    }
  }
}

Set monthly postpaid spending limits

/v1/billing/teams/{team_id}/postpaid/spending-limits

Set the postpaid monthly spending limit of a team. This can be used to restrict the maximum amount of postpaid API usage. Note this will not limit the amount of prepaid credit usage, and prepaid credits will always be consumed before accruing postpaid usage. To use only prepaid credits, you can set this limit to 0.

Path Parameters

team_idstring

Team ID.

Request Body

Response Body

thisBpSoftSpendingLimitobject

Representation of USD Cents.

{
  "desiredSoftSpendingLimit": {
    "val": "20000"
  }
}

{
  "thisBpSoftSpendingLimit": {
    "val": "20000"
  }
}

List prepaid credit balance and balance changes

/v1/billing/teams/{team_id}/prepaid/balance

List the prepaid credit balance and balance changes of a team.

Path Parameters

team_idstring

The team ID of the team.

Response Body

changesarray<object>

The changes of the prepaid credit balance.

totalobject

Representation of USD Cents.

No parameters.

{
  "changes": [
    {
      "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
      "changeOrigin": "PURCHASE",
      "topupStatus": "SUCCEEDED",
      "amount": {
        "val": "-1000"
      },
      "invoiceId": "7v7blf6c1G2g34OdI4N5tD1CKCdag4ZYLhn5vTBLIMM=",
      "invoiceNumber": "062-446-653-166",
      "createTime": "2025-02-24T15:28:02.308840Z",
      "paymentProcessor": {
        "kind": "STRIPE"
      }
    }
  ],
  "total": {
    "val": "-1000"
  }
}

Top up prepaid credit

/v1/billing/teams/{team_id}/prepaid/top-up

Top up prepaid credit using the default payment method.

Path Parameters

team_idstring

Team ID of the team to top up for.

Request Body

Response Body

changeobject

Change item on the prepaid credit balance.

{
  "amount": {
    "val": "500"
  }
}

{
  "change": {
    "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
    "changeOrigin": "PURCHASE",
    "topupStatus": "TO_CHARGE",
    "amount": {
      "val": "-500"
    },
    "createTime": "2025-11-13T14:02:21.309537Z",
    "createTs": "2025-11-13T14:02:21.309537Z",
    "paymentProcessor": {
      "kind": "STRIPE"
    }
  }
}

Daily token usage

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.

Value	Measures
`usd`	Cost in USD
`units`	Tokens for token unit types; other units, such as images or audio seconds, for the rest
`items`	Billing items; one request produces an item for each priced dimension
`transactions`	Requests

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.

Split long- vs short-context tokens

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"].

Get historical usage of the API

/v1/billing/teams/{team_id}/usage

Get historical usage of the API (spend, token and other unit counts) over a time period, bucketed by time and grouped by fields. For daily token counts, sum `units` per day grouped by `unit_type`.

Path Parameters

team_idstring

The team whose billing records to analyze.

Request Body

Response Body

timeSeriesarray<object>

For each value of the group-by clause, we return one time series.

limitReachedboolean

If this is true, the maximum cardinality of the query has been reached and only a subset of results is returned.

{
  "analyticsRequest": {
    "timeRange": {
      "startTime": "2025-10-01 00:00:00",
      "endTime": "2025-10-08 00:00:00",
      "timezone": "Etc/GMT"
    },
    "timeUnit": "TIME_UNIT_DAY",
    "values": [
      {
        "name": "units",
        "aggregation": "AGGREGATION_SUM"
      }
    ],
    "groupBy": [
      "unit_type",
      "description"
    ],
    "filters": []
  }
}

{
  "timeSeries": [
    {
      "group": [
        "Chat grok-4-0709"
      ],
      "groupLabels": [
        "Chat grok-4-0709"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0.75973725
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    },
    {
      "group": [
        "Chat grok-4-fast-non-reasoning"
      ],
      "groupLabels": [
        "Chat grok-4-fast-non-reasoning"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0.0001037
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    },
    {
      "group": [
        "grok-2-image-1212"
      ],
      "groupLabels": [
        "grok-2-image-1212"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0.14
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    }
  ],
  "limitReached": false
}

Last updated:November 3, 2026