## GetEnterpriseAIUsageSummary

`billing.get_enterprise_ai_usage_summary(BillingGetEnterpriseAIUsageSummaryParams**kwargs)  -> BillingGetEnterpriseAIUsageSummaryResponse`

**post** `/gitpod.v1.BillingService/GetEnterpriseAIUsageSummary`

Returns organization-level enterprise AI usage totals for reporting.

Reports BYOK (bring-your-own-key) token spend: cost in the
organization's billing currency plus token counts, with a per-model
breakdown. Credit-based usage from managed models is not included and
the credits field is not populated by this endpoint.

Use this method to:

- Report total BYOK AI spend (cost and tokens) for a date range
- Break down organization usage by model

Only available for enterprise organizations.

### Examples

- Get usage totals for January:

  Returns organization-wide BYOK spend for the month. 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 summary. 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`

- `timezone: Optional[str]`

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

### Returns

- `class BillingGetEnterpriseAIUsageSummaryResponse: …`

  - `budget: Optional[EnterpriseAIUsageBudget]`

    budget is unset when no monthly budget applies to the organization.

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

  - `calculated_at: Optional[datetime]`

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

  - `usage: Optional[EnterpriseAIUsage]`

  - `usage_by_model: Optional[List[EnterpriseAIUsageByModel]]`

    - `model: Optional[str]`

    - `unpriced_usage: Optional[EnterpriseAIUsage]`

      Usage excluded from spend because no matching BYOK rate was configured.

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

    - `usage: Optional[EnterpriseAIUsage]`

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

      - `token_type: Optional[ByokRateCardTokenType]`

      - `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
)
response = client.billing.get_enterprise_ai_usage_summary(
    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",
)
print(response.budget)
```

#### Response

```json
{
  "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
  },
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "usage": {
    "costMicrounits": "costMicrounits",
    "credits": 0,
    "currency": "BILLING_CURRENCY_UNSPECIFIED",
    "tokens": {
      "cacheTokens": "cacheTokens",
      "inputTokens": "inputTokens",
      "outputTokens": "outputTokens",
      "totalTokens": "totalTokens"
    }
  },
  "usageByModel": [
    {
      "model": "model",
      "unpricedUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "unpricedUsageByTokenType": [
        {
          "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"
            }
          }
        }
      ],
      "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"
            }
          }
        }
      ]
    }
  ]
}
```