Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

ListEnterpriseAITeamUsage

billing.list_enterprise_ai_team_usage(BillingListEnterpriseAITeamUsageParams**kwargs) -> SyncTeamUsagePage[TeamEnterpriseAIUsage]
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.

ParametersExpand Collapse
date_range: DateRange

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.

end_time: datetime

End time of the date range (exclusive).

formatdate-time
start_time: datetime

Start time of the date range (inclusive).

formatdate-time
organization_id: str
formatuuid
token: Optional[str]
page_size: Optional[int]
maximum100
minimum0
filter: Optional[Filter]
team_ids: Optional[Sequence[str]]
timezone: Optional[str]

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

maxLength64
ReturnsExpand Collapse
class TeamEnterpriseAIUsage: …
budget: Optional[EnterpriseAIUsageBudget]

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"
monthly_cost_limit_microunits: Optional[str]
monthly_credit_limit: Optional[str]
month_to_date_usage: Optional[EnterpriseAIUsage]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
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"
utilization_percent: Optional[float]
formatdouble
display_name: Optional[str]
team_id: Optional[str]
formatuuid
usage: Optional[EnterpriseAIUsage]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
usage_by_token_type: Optional[List[EnterpriseAIUsageByTokenType]]
token_type: 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]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]

ListEnterpriseAITeamUsage

import os
from datetime import datetime
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
page = client.billing.list_enterprise_ai_team_usage(
    date_range={
        "end_time": datetime.fromisoformat("2024-01-31T00:00:00"),
        "start_time": datetime.fromisoformat("2024-01-01T00:00:00"),
    },
    organization_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047",
)
page = page.team_usage[0]
print(page.budget)
{
  "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"
            }
          }
        }
      ]
    }
  ]
}