ListEnterpriseAIUserUsage

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.

Query ParametersExpand Collapse

token: optional string

pageSize: optional number

maximum100

minimum0

Body ParametersJSONExpand Collapse

dateRange: DateRange { endTime, startTime }

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.

endTime: string

End time of the date range (exclusive).

formatdate-time

startTime: string

Start time of the date range (inclusive).

formatdate-time

organizationId: string

formatuuid

filter: optional object { subject }

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 { id, principal }

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 string

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"

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.

formatint32

maximum100

sort: optional object { field, order }

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

field: optional "SORT_FIELD_UNSPECIFIED" or "SORT_FIELD_USAGE" or "SORT_FIELD_DISPLAY_NAME" or 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 string

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

maxLength64

ReturnsExpand Collapse

calculatedAt: optional string

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

formatdate-time

pagination: optional object { nextToken }

nextToken: optional string

Token passed for retrieving the next set of results. Empty if there are no more results

totalCount: optional number

Total number of users with usage in the billing period, across all pages.

formatint32

userUsage: optional array of UserCostBudgetUsage { budgetSource, currency, displayName, 7 more }

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

displayName: optional string

isServiceAccount: optional boolean

monthlyCostLimitMicrounits: optional string

monthToDateUsage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

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

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

noCap: optional boolean

overBudget: optional boolean

userId: optional string

utilizationPercent: optional number

formatdouble

ListEnterpriseAIUserUsage

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage \
    -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"
        }'

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