Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

ListEnterpriseAIUserUsage

billing.list_enterprise_ai_user_usage(BillingListEnterpriseAIUserUsageParams**kwargs) -> SyncUserUsagePage[UserCostBudgetUsage]
POST/gitpod.v1.BillingService/ListEnterpriseAIUserUsage

Lists enterprise AI usage grouped by user with effective monthly budget data.

Reports BYOK token spend (cost and tokens) for each user and service account with attributed usage in the date range, including each subject’s effective monthly budget. Usage not attributed to a user or service account is excluded, so the sum across subjects can be less than the organization totals from GetEnterpriseAIUsageSummary. The credits field is not populated by this endpoint.

Budget fields (month_to_date_usage, utilization_percent, over_budget) are computed from usage inside the requested date range measured against the monthly limit. Send a range that starts on the first day of the month for true month-to-date figures.

Use this method to:

  • Export per-user BYOK AI spend to external reporting
  • Identify the highest spenders in the organization
  • Track per-user budget utilization and over-budget users

Only available for enterprise organizations.

Examples

  • List user usage for January:

    Returns per-user BYOK spend with effective budgets, highest spend first. 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. Callers without it can read their own usage by setting filter.subject to themselves.

ParametersExpand Collapse
date_range: DateRange

Date range for the user 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]

Optional filter narrowing the returned user usage. When set to a subject, the response contains only usage for that user or service account.

subject: Optional[Subject]

Restrict the user usage list to a single subject. The subject must be PRINCIPAL_USER or PRINCIPAL_SERVICE_ACCOUNT and belong to the request’s organization.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[Principal]

Principal is the principal of the subject

One of the following:
"PRINCIPAL_UNSPECIFIED"
"PRINCIPAL_ACCOUNT"
"PRINCIPAL_USER"
"PRINCIPAL_RUNNER"
"PRINCIPAL_ENVIRONMENT"
"PRINCIPAL_SERVICE_ACCOUNT"
"PRINCIPAL_RUNNER_MANAGER"
sort: Optional[Sort]

sort controls the ordering of results. Defaults to total spend descending.

field: Optional[Literal["SORT_FIELD_UNSPECIFIED", "SORT_FIELD_USAGE", "SORT_FIELD_DISPLAY_NAME", 2 more]]
One of the following:
"SORT_FIELD_UNSPECIFIED"
"SORT_FIELD_USAGE"
"SORT_FIELD_DISPLAY_NAME"
"SORT_FIELD_BUDGET"
"SORT_FIELD_BUDGET_USED"
order: Optional[SortOrder]
One of the following:
"SORT_ORDER_UNSPECIFIED"
"SORT_ORDER_ASC"
"SORT_ORDER_DESC"
timezone: Optional[str]

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

maxLength64
ReturnsExpand Collapse
class UserCostBudgetUsage: …
budget_source: Optional[EnterpriseAIUserBudgetPolicySource]
One of the following:
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_NONE"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER"
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
display_name: Optional[str]
is_service_account: Optional[bool]
monthly_cost_limit_microunits: Optional[str]
month_to_date_usage: Optional[EnterpriseAIUsage]

Usage within the requested date range. Reflects true month-to-date usage when the range starts on the first day of the month.

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]
no_cap: Optional[bool]
over_budget: Optional[bool]
user_id: Optional[str]
utilization_percent: Optional[float]
formatdouble

ListEnterpriseAIUserUsage

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_user_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.user_usage[0]
print(page.budget_source)
{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "currency": "BILLING_CURRENCY_UNSPECIFIED",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
      "monthToDateUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "noCap": true,
      "overBudget": true,
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}
Returns Examples
{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "currency": "BILLING_CURRENCY_UNSPECIFIED",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
      "monthToDateUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "noCap": true,
      "overBudget": true,
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}