English Docs
API Console

Management API

Billing Management

View as Markdown
Create API key Learn Grok 4.7

Get billing information

/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.

Exampletext

text

No parameters.
Exampletext

text

{
  "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

Exampletext

text

{
  "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"
  }
}
Exampletext

text

{}

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.

Exampletext

text

No parameters.
Exampletext

text

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

Exampletext

text

No parameters.
Exampletext

text

{
  "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

Exampletext

text

{
  "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx"
}
Exampletext

text

{}

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

Exampletext

text

No parameters.
Exampletext

text

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

Exampletext

text

No parameters.
Exampletext

text

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

Exampletext

text

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

text

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

Exampletext

text

No parameters.
Exampletext

text

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

Exampletext

text

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

text

{
  "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"
    }
  }
}

Get historical usage of the API

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

Get historical usage of the API over a time period, aggregated by fields.

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.

Exampletext

text

{
  "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": []
  }
}
Exampletext

text

{
  "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:February 13, 2026