> ## Documentation Index > Fetch the complete documentation index at: https://ona.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Enterprise AI Usage Time Series > Returns daily enterprise AI usage totals for the organization. `Unary` ยท [`Billing`](/docs/api-reference/generated/billing/overview) Returns daily enterprise AI usage totals for the organization. Each day reports BYOK token spend (cost and tokens) with per-user, per-team, and per-model breakdowns. Per-user entries cover the top spenders with the remainder aggregated into an "Others" bucket; usage not attributed to a user or service account appears only in the daily totals. The credits field is not populated by this endpoint. When filter.subject is set the response contains only that subject's usage: daily totals and the team breakdown are omitted, and the model breakdown covers the subject only. Use this method to: * Chart daily BYOK AI spend over a date range * Feed daily per-user usage into external dashboards * Restrict the response to a single user or service account Only available for enterprise organizations. ### Examples * Get daily usage for January: Returns one entry per day with per-user, per-team, and per-model breakdowns. Both dates are inclusive and the range must not exceed 31 days. ```yaml theme={null} 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. ## Endpoint ```text theme={null} POST /api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries ``` Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain. ## Request example ```bash cURL theme={null} export ONA_HOST=https://app.ona.com export ONA_API_KEY= curl --request POST \ --url "$ONA_HOST/api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "dateRange": { "endTime": "2026-01-01T00:00:00Z", "startTime": "2026-01-01T00:00:00Z" }, "organizationId": "" }' ``` ```python Python theme={null} import gitpod.v1.billing_pb2 as billing_pb2 import gitpod.v1.usage_pb2 as usage_pb2 import google.protobuf.timestamp_pb2 as timestamp_pb2 from ona_sdk import create_client_from_env ona = create_client_from_env() request = billing_pb2.GetEnterpriseAIUsageTimeSeriesRequest( organization_id="", date_range=usage_pb2.DateRange( start_time=timestamp_pb2.Timestamp(seconds=1767225600), end_time=timestamp_pb2.Timestamp(seconds=1767225600), ), ) response = ona.services.billing.get_enterprise_ai_usage_time_series(request) print(response) ``` ```typescript TypeScript theme={null} import { create } from "@bufbuild/protobuf"; import { createClientFromEnv } from "@gitpod/sdk"; import { GetEnterpriseAIUsageTimeSeriesRequestSchema } from "@gitpod/sdk/gitpod/v1/billing_pb"; import { timestampFromDate } from "@bufbuild/protobuf/wkt"; async function main() { const ona = createClientFromEnv(); const request = create(GetEnterpriseAIUsageTimeSeriesRequestSchema, { organizationId: "", dateRange: { startTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")), endTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")), }, }); const response = await ona.services.billing.getEnterpriseAIUsageTimeSeries(request); console.log(response); } main().catch(console.error); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "connectrpc.com/connect" "github.com/gitpod-io/gitpod-sdk-go/sdk" gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1" timestamppb "google.golang.org/protobuf/types/known/timestamppb" ) func main() { ona, err := sdk.NewFromEnv() if err != nil { log.Fatal(err) } request := connect.NewRequest(&gitpodpb.GetEnterpriseAIUsageTimeSeriesRequest{ OrganizationId: "", DateRange: &gitpodpb.DateRange{ StartTime: ×tamppb.Timestamp{Seconds: 1767225600}, EndTime: ×tamppb.Timestamp{Seconds: 1767225600}, }, }) response, err := ona.Services.Billing.GetEnterpriseAIUsageTimeSeries(context.Background(), request) if err != nil { log.Fatal(err) } fmt.Println(response.Msg) } ``` ```json Request body theme={null} { "dateRange": { "endTime": "2026-01-01T00:00:00Z", "startTime": "2026-01-01T00:00:00Z" }, "organizationId": "" } ``` ## Request `gitpod.v1.GetEnterpriseAIUsageTimeSeriesRequest` | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | string | Yes | Constraints: `required=true, string.uuid=true`. | | `dateRange` | [DateRange](#type-gitpod-v1-date-range) | Yes | Date range for the daily usage series. Both start and end dates are inclusive. Time-of-day is ignored; dates are truncated to midnight in the specified timezone. Constraints: `required=true`. | | `timezone` | string | No | IANA timezone name used to bucket daily usage. When empty, defaults to "UTC". Constraints: `string.max_len=64`. | | `filter` | [EnterpriseAIUsageTimeSeriesFilter](#type-gitpod-v1-enterprise-ai-usage-time-series-filter) | No | | ## Response `gitpod.v1.GetEnterpriseAIUsageTimeSeriesResponse` | Field | Type | Required | Description | | -------------- | ---------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `calculatedAt` | RFC 3339 timestamp | No | calculated\_at is the time through which usage has been calculated. Usage after this timestamp may still be processing. | | `dailyUsage` | array of [DailyEnterpriseAIUsage](#type-gitpod-v1-daily-enterprise-ai-usage) | No | | ## Related types `gitpod.v1.DailyEnterpriseAIUsage` | Field | Type | Required | Description | | -------------- | --------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `date` | RFC 3339 timestamp | Yes | Constraints: `required=true`. | | `usage` | [EnterpriseAIUsage](#type-gitpod-v1-enterprise-ai-usage) | No | | | `budget` | [EnterpriseAIUsageBudget](#type-gitpod-v1-enterprise-ai-usage-budget) | No | budget is unset when no monthly budget applies to the organization. | | `userUsage` | array of [UserEnterpriseAIUsage](#type-gitpod-v1-user-enterprise-ai-usage) | No | | | `teamUsage` | array of [TeamEnterpriseAIUsage](#type-gitpod-v1-team-enterprise-ai-usage) | No | | | `usageByModel` | array of [EnterpriseAIUsageByModel](#type-gitpod-v1-enterprise-ai-usage-by-model) | No | Usage for this day broken down by model. When the request filters by subject, contains only that subject's model usage. | DateRange specifies a time period for queries. `gitpod.v1.DateRange` | Field | Type | Required | Description | | ----------- | ------------------ | -------- | ----------------------------------------------------------------------- | | `startTime` | RFC 3339 timestamp | Yes | Start time of the date range (inclusive). Constraints: `required=true`. | | `endTime` | RFC 3339 timestamp | Yes | End time of the date range (exclusive). Constraints: `required=true`. | `gitpod.v1.EnterpriseAIUsage` | Field | Type | Required | Description | | ---------------- | --------------------------------------------------- | -------- | -------------------------------------- | | `credits` | number | No | Constraints: `double.gte=0`. | | `costMicrounits` | 64-bit integer string | No | Constraints: `int64.gte=0`. | | `currency` | [BillingCurrency](#enum-gitpod-v1-billing-currency) | No | Constraints: `enum.defined_only=true`. | | `tokens` | EnterpriseAITokenUsage | No | | `gitpod.v1.EnterpriseAIUsageBudget` | Field | Type | Required | Description | | ---------------------------- | ---------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- | | `source` | [EnterpriseAIUsageBudgetSource](#enum-gitpod-v1-enterprise-ai-usage-budget-source) | No | Constraints: `enum.defined_only=true, enum.not_in=0`. | | `monthlyCreditLimit` | 64-bit integer string | No | Constraints: `int64.gte=0`. | | `monthlyCostLimitMicrounits` | 64-bit integer string | No | Constraints: `int64.gte=0`. | | `currency` | [BillingCurrency](#enum-gitpod-v1-billing-currency) | No | Constraints: `enum.defined_only=true`. | | `monthToDateUsage` | EnterpriseAIUsage | No | | | `utilizationPercent` | number | No | Constraints: `double.gte=0`. | `gitpod.v1.EnterpriseAIUsageByModel` | Field | Type | Required | Description | | -------------------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------- | | `model` | string | No | | | `usage` | EnterpriseAIUsage | No | | | `usageByTokenType` | array of EnterpriseAIUsageByTokenType | No | | | `unpricedUsage` | EnterpriseAIUsage | No | Usage excluded from spend because no matching BYOK rate was configured. | | `unpricedUsageByTokenType` | array of EnterpriseAIUsageByTokenType | No | | `gitpod.v1.EnterpriseAIUsageTimeSeriesFilter` | Field | Type | Required | Description | | --------- | ---------------------------------- | -------- | ---------------------------------------------------- | | `subject` | [Subject](#type-gitpod-v1-subject) | No | Restrict the per-user breakdown to a single subject. | `gitpod.v1.Subject` | Field | Type | Required | Description | | ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------- | | `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. | | `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. | `gitpod.v1.TeamEnterpriseAIUsage` | Field | Type | Required | Description | | ------------------ | ------------------------------------- | -------- | ------------------------------------------------------------ | | `teamId` | string | No | Constraints: `string.uuid=true`. | | `displayName` | string | No | | | `usage` | EnterpriseAIUsage | No | | | `budget` | EnterpriseAIUsageBudget | No | budget is unset when no monthly budget applies to this team. | | `usageByTokenType` | array of EnterpriseAIUsageByTokenType | No | | `gitpod.v1.UserEnterpriseAIUsage` | Field | Type | Required | Description | | ------------- | ----------------- | -------- | -------------------------------------------------------- | | `userId` | string | No | Empty when representing the "Others" aggregation bucket. | | `displayName` | string | No | | | `usage` | EnterpriseAIUsage | No | | | Value | Number | Description | | ------------------------------ | -----: | ----------- | | `BILLING_CURRENCY_UNSPECIFIED` | 0 | | | `BILLING_CURRENCY_USD` | 1 | | | `BILLING_CURRENCY_EUR` | 2 | | | `BILLING_CURRENCY_GBP` | 3 | | | Value | Number | Description | | ------------------------------------------------ | -----: | ----------- | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED` | 0 | | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION` | 1 | | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM` | 2 | | | Value | Number | Description | | --------------------------- | -----: | ----------- | | `PRINCIPAL_UNSPECIFIED` | 0 | | | `PRINCIPAL_ACCOUNT` | 1 | | | `PRINCIPAL_USER` | 2 | | | `PRINCIPAL_RUNNER` | 3 | | | `PRINCIPAL_ENVIRONMENT` | 4 | | | `PRINCIPAL_SERVICE_ACCOUNT` | 5 | | | `PRINCIPAL_RUNNER_MANAGER` | 6 | |