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

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

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `dateRange: 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.

  - `endTime: string`

    End time of the date range (exclusive).

  - `startTime: string`

    Start time of the date range (inclusive).

- `organizationId: string`

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

- `timezone: optional string`

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

### Returns

- `calculatedAt: optional string`

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

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

    - `monthlyCostLimitMicrounits: optional string`

    - `monthlyCreditLimit: optional string`

    - `monthToDateUsage: optional EnterpriseAIUsage`

      - `costMicrounits: optional string`

      - `credits: optional number`

      - `currency: optional BillingCurrency`

      - `tokens: optional EnterpriseAITokenUsage`

        - `cacheTokens: optional string`

        - `inputTokens: optional string`

        - `outputTokens: optional string`

        - `totalTokens: optional string`

    - `source: optional EnterpriseAIUsageBudgetSource`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED"`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION"`

      - `"ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM"`

    - `utilizationPercent: optional number`

  - `displayName: optional string`

  - `teamId: optional string`

  - `usage: optional EnterpriseAIUsage`

  - `usageByTokenType: optional array of EnterpriseAIUsageByTokenType`

    - `tokenType: 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

```http
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"
        }'
```

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