ListEnterpriseAITeamUsage

POST/gitpod.v1.BillingService/ListEnterpriseAITeamUsage

Lists enterprise AI usage grouped by team.

Reports BYOK token spend per team (cost and tokens) with each team’s monthly budget when one applies. The credits field is not populated by this endpoint.

Use this method to:

Compare BYOK AI spend across teams
Track team budget utilization
Filter usage to specific teams

Only available for enterprise organizations.

Examples

List team usage for January:

Returns BYOK spend per team with monthly budgets. Both dates are inclusive and the range must not exceed 31 days.

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
dateRange:
  startTime: "2024-01-01T00:00:00Z"
  endTime: "2024-01-31T00:00:00Z"

Authorization

Requires billing:read_usage permission on the organization.

Query ParametersExpand Collapse

token: optional string

pageSize: optional number

maximum100

minimum0

Body ParametersJSONExpand Collapse

dateRange: DateRange { endTime, startTime }

Date range for the team usage list. Both start and end dates are inclusive. Time-of-day is ignored; dates are truncated to midnight in the specified timezone.

endTime: string

End time of the date range (exclusive).

formatdate-time

startTime: string

Start time of the date range (inclusive).

formatdate-time

organizationId: string

formatuuid

filter: optional object { teamIds }

teamIds: optional array of string

pagination: optional object { token, pageSize }

token: optional string

Token for the next set of results that was returned as next_token of a PaginationResponse

pageSize: optional number

Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.

formatint32

maximum100

timezone: optional string

IANA timezone name used to bucket usage. When empty, defaults to “UTC”.

maxLength64

ReturnsExpand Collapse

calculatedAt: optional string

calculated_at is the time through which usage has been calculated. Usage after this timestamp may still be processing.

formatdate-time

pagination: optional object { nextToken }

nextToken: optional string

Token passed for retrieving the next set of results. Empty if there are no more results

teamUsage: optional array of TeamEnterpriseAIUsage { budget, displayName, teamId, 2 more }

budget: optional EnterpriseAIUsageBudget { currency, monthlyCostLimitMicrounits, monthlyCreditLimit, 3 more }

budget is unset when no monthly budget applies to this team.

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

monthlyCostLimitMicrounits: optional string

monthlyCreditLimit: optional string

monthToDateUsage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

source: optional EnterpriseAIUsageBudgetSource

One of the following:

"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED"

"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION"

"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM"

utilizationPercent: optional number

formatdouble

displayName: optional string

teamId: optional string

formatuuid

usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

usageByTokenType: optional array of EnterpriseAIUsageByTokenType { tokenType, usage }

tokenType: optional ByokRateCardTokenType

One of the following:

"BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"

"BYOK_RATE_CARD_TOKEN_TYPE_INPUT"

"BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"

"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"

"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"

usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

ListEnterpriseAITeamUsage

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "dateRange": {
            "endTime": "2024-01-31T00:00:00Z",
            "startTime": "2024-01-01T00:00:00Z"
          },
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'

{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "teamUsage": [
    {
      "budget": {
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
        "monthlyCreditLimit": "monthlyCreditLimit",
        "monthToDateUsage": {
          "costMicrounits": "costMicrounits",
          "credits": 0,
          "currency": "BILLING_CURRENCY_UNSPECIFIED",
          "tokens": {
            "cacheTokens": "cacheTokens",
            "inputTokens": "inputTokens",
            "outputTokens": "outputTokens",
            "totalTokens": "totalTokens"
          }
        },
        "source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED",
        "utilizationPercent": 0
      },
      "displayName": "displayName",
      "teamId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "usage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "usageByTokenType": [
        {
          "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
          "usage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          }
        }
      ]
    }
  ]
}

Returns Examples

{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "teamUsage": [
    {
      "budget": {
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
        "monthlyCreditLimit": "monthlyCreditLimit",
        "monthToDateUsage": {
          "costMicrounits": "costMicrounits",
          "credits": 0,
          "currency": "BILLING_CURRENCY_UNSPECIFIED",
          "tokens": {
            "cacheTokens": "cacheTokens",
            "inputTokens": "inputTokens",
            "outputTokens": "outputTokens",
            "totalTokens": "totalTokens"
          }
        },
        "source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED",
        "utilizationPercent": 0
      },
      "displayName": "displayName",
      "teamId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "usage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "usageByTokenType": [
        {
          "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
          "usage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          }
        }
      ]
    }
  ]
}