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

  ```yaml
  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.

### Parameters

- `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).

  - `start_time: datetime`

    Start time of the date range (inclusive).

- `organization_id: str`

- `token: Optional[str]`

- `page_size: Optional[int]`

- `filter: Optional[Filter]`

  - `team_ids: Optional[Sequence[str]]`

- `pagination: Optional[Pagination]`

  - `token: Optional[str]`

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

  - `page_size: Optional[int]`

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

- `timezone: Optional[str]`

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

### Returns

- `class TeamEnterpriseAIUsage: …`

  - `budget: Optional[EnterpriseAIUsageBudget]`

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

    - `currency: Optional[BillingCurrency]`

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

      - `currency: Optional[BillingCurrency]`

      - `tokens: Optional[EnterpriseAITokenUsage]`

        - `cache_tokens: Optional[str]`

        - `input_tokens: Optional[str]`

        - `output_tokens: Optional[str]`

        - `total_tokens: Optional[str]`

    - `source: Optional[EnterpriseAIUsageBudgetSource]`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED"`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION"`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM"`

    - `utilization_percent: Optional[float]`

  - `display_name: Optional[str]`

  - `team_id: Optional[str]`

  - `usage: Optional[EnterpriseAIUsage]`

  - `usage_by_token_type: Optional[List[EnterpriseAIUsageByTokenType]]`

    - `token_type: Optional[ByokRateCardTokenType]`

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

### Example

```python
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)
```

#### Response

```json
{
  "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"
            }
          }
        }
      ]
    }
  ]
}
```