> ## 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. # Ona Intelligence usage API Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more. The Ona Intelligence usage API exposes the credit consumption data behind **Settings → Cost & Budgets**: daily usage broken down by type and by user, team, environment, and conversation; cumulative period totals with team allocations and per-user budgets; and a CSV export. Use it to export usage to finance tools, attribute spend across teams, or track budget utilization. ## Ona Intelligence or BYOK? Choose the right API Ona meters AI usage one of two ways, depending on how your organization is set up. The two models have separate APIs: | Your setup | How usage is metered | Use | | ----------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | | **Ona Intelligence** (Ona-managed models) | Credits (OCUs) consumed as you use environments and AI | **This API** | | **BYOK** (your own provider keys) | Spend in your billing currency, via BYOK rate cards | **[AI cost usage API](/ona/billing/cost-usage-api)** | **Not sure which applies to you?** Open **Settings → Cost & Budgets**: if usage is shown in **credits**, you are using Ona Intelligence (use this API); if it is shown as **spend in a currency** (USD, EUR, or GBP), you are on BYOK (use the cost usage API). The APIs also tell you directly: this API returns `FAILED_PRECONDITION` with `enterprise credit usage is not enabled` for BYOK-only organizations, and the cost endpoints return empty usage for organizations on Ona Intelligence. ## Authentication All endpoints accept a Bearer token: a [personal access token](/ona/integrations/personal-access-token) (acts as you) or a [service account token](/ona/organizations/service-accounts) (owned by the organization, recommended for ongoing automation). ```bash theme={null} export GITPOD_API_KEY="your-token" ``` Organization admins and members with the [Billing Viewer](/ona/organizations/organization-roles#billing-viewer) role can read all usage. Other members can read their own usage on the report endpoint by setting `filter.subject` to their own user identity (this self-access path is for user tokens, not service accounts). ## Request format Every endpoint is a POST with a JSON body: ```text theme={null} POST https://app.gitpod.io/api/gitpod.v1.BillingService/ ``` | Parameter | Required | Description | | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | Yes | Your organization ID. | | `dateRange` | Report, export | `startTime` and `endTime` as RFC-3339 timestamps. Both dates are inclusive; time-of-day is ignored. The report is capped at 31 days; the export may cover up to a year. | | `asOf` | Cumulative, list | Point in time to compute month-to-date usage up to. Defaults to now. | | `timezone` | No | IANA timezone name (for example `Europe/London`) used to bucket daily usage. Defaults to `UTC`. | | `pagination` | List | `pageSize` and `token` for paging. | Response conventions: * Credits are floating-point values (for example `12.5`). Budgets (`creditBudget`) are whole credits. * `usageType` is `USAGE_TYPE_ENVIRONMENT` (environment runtime) or `USAGE_TYPE_AGENTIC` (agent activity). * Token counts are returned as JSON strings, per protobuf JSON encoding. * Fields at their default value are omitted. `creditBudget`, `utilizationPercent`, and `overBudget` appear on a user only when a budget applies, `overBudget` and `isServiceAccount` only when true, and an unset budget or zero usage leaves the field out entirely. * `periodStart` marks the start of the billing period; usage before it is excluded. ## Daily usage report Returns one entry per day: org-wide credits by usage type, plus per-user, per-team, per-environment, and per-conversation breakdowns (top consumers with the rest grouped into an "Others" bucket), and a per-model breakdown of agent usage. **Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport` **Request:** ```bash theme={null} curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "organizationId": "", "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"} }' ``` **Response:** ```json theme={null} { "updatedAt": "2026-07-09T12:00:00Z", "periodStart": "2026-01-01T00:00:00Z", "dailyUsage": [ { "date": "2026-06-01T00:00:00Z", "orgUsage": [ { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 41.5 }, { "usageType": "USAGE_TYPE_AGENTIC", "credits": 918.25 } ], "userUsage": [ { "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 930.49 }] }, { "userId": "", "displayName": "Others", "usage": [{ "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 33.0 }] } ], "teamUsage": [ { "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047", "displayName": "Platform", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 622.31 }] } ], "environmentUsage": [ { "environmentId": "0191e4b2-6b3c-7973-a78b-68dc4a6da6b2", "displayName": "my-service", "usage": [{ "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 22.4 }] } ], "conversationUsage": [ { "agentExecutionId": "019ee14b-2596-771d-82d2-ef9d3d16465d", "displayName": "Add pagination to the users table", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 231.87 }] } ], "usageByModel": [ { "model": "claude-opus-4-8", "usage": { "credits": 930.49, "tokens": { "inputTokens": "166562", "outputTokens": "898901", "cacheTokens": "154015590", "totalTokens": "155081053" } }, "usageByTokenType": [ { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ", "usage": { "credits": 892.86, "tokens": { "cacheTokens": "148810014", "totalTokens": "148810014" } } }, { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT", "usage": { "credits": 5.39, "tokens": { "outputTokens": "898901", "totalTokens": "898901" } } } ] } ] } ] } ``` An empty `userId` (or `teamId`, `environmentId`, `agentExecutionId`) marks the "Others" bucket. Each `userUsage` entry also carries a `usageByModel` breakdown with the same shape as the day-level one shown here; `teamUsage`, `environmentUsage`, and `conversationUsage` do not. Token types (`BYOK_RATE_CARD_TOKEN_TYPE_INPUT`, `_OUTPUT`, `_CACHE_READ`, `_CACHE_WRITE`) apply to both Ona Intelligence and BYOK usage. To restrict the report to one subject, set `filter.subject`: ```bash theme={null} curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "organizationId": "", "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"}, "filter": {"subject": {"id": "", "principal": "PRINCIPAL_USER"}} }' ``` When `filter.subject` is set, each day's `userUsage` contains only that subject (no "Others" bucket), and the org, team, environment, and conversation breakdowns are omitted. ## Cumulative period usage Returns period-to-date totals for the organization, each team (with its credit allocation), members not on any team, and per-user month-to-date usage with budgets. **Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCumulativeCreditUsage` **Request:** ```bash theme={null} curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCumulativeCreditUsage \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{"organizationId": ""}' ``` **Response:** ```json theme={null} { "periodStart": "2026-01-01T00:00:00Z", "orgUsage": { "totalCredits": 1840.75, "usageByType": [ { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 1290.5 }, { "usageType": "USAGE_TYPE_AGENTIC", "credits": 550.25 } ] }, "teamUsage": [ { "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047", "displayName": "Platform", "usage": { "totalCredits": 620.0, "usageByType": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 240.0 }] }, "creditBudget": "1000" } ], "unteamedUsage": { "totalCredits": 90.0 }, "userUsage": [ { "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "monthToDateUsage": { "totalCredits": 120.5, "usageByType": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 120.5 }] }, "creditBudget": "150", "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION", "utilizationPercent": 80.3, "usageByModel": [ { "model": "claude-opus-4-8", "usage": { "credits": 120.5, "tokens": { "inputTokens": "103422", "outputTokens": "63100", "cacheTokens": "35707859", "totalTokens": "35874381" } } } ] } ] } ``` `teamUsage` returns all teams (no top-N limit). The `userUsage` list is not paginated or capped; for large organizations prefer the paginated list endpoint below. Each user carries a `usageByModel` breakdown; budget fields appear only when a monthly budget applies (`overBudget` only when the user is over it), and `noCap` is `true` for users exempted from limits. ## Per-user usage list Returns per-user month-to-date usage with budgets, paginated. Ordered by total credits descending by default so the highest spenders appear first. **Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage` **Request:** ```bash theme={null} curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "organizationId": "", "sort": {"field": "SORT_FIELD_USAGE", "order": "SORT_ORDER_DESC"}, "pagination": {"pageSize": 50} }' ``` **Response:** ```json theme={null} { "totalCount": 24, "pagination": { "nextToken": "d2c94c27-3b76-4a42-b88c-95a85e392c68" }, "userUsage": [ { "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "monthToDateUsage": { "totalCredits": 1320.37, "usageByType": [ { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 177.78 }, { "usageType": "USAGE_TYPE_AGENTIC", "credits": 1142.59 } ] }, "creditBudget": "500", "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER", "utilizationPercent": 264.07, "overBudget": true, "usageByModel": [ { "model": "claude-opus-4-8", "usage": { "credits": 1142.59, "tokens": { "inputTokens": "166562", "outputTokens": "898901", "cacheTokens": "154015590", "totalTokens": "155081053" } } } ] } ] } ``` The page token (`nextToken`) is the last user's ID. `budgetSource` is `ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION`, `_USER`, or `_NONE`. Sort fields: `SORT_FIELD_USAGE` (default, total credits), `SORT_FIELD_DISPLAY_NAME`, `SORT_FIELD_BUDGET`, `SORT_FIELD_BUDGET_USED`. The default usage ordering paginates over any number of users. The other three sorts compute the order in memory and are limited to organizations with at most 10,000 users; beyond that, use `SORT_FIELD_USAGE`. Because month-to-date figures are recomputed per request, hold `asOf` stable across a paginated walk to keep page tokens valid. ## CSV export Returns a short-lived, signed download URL for a gzip-compressed CSV. The download must be made by the same principal that requested it, carrying its own bearer token. **Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageExport` **Request:** ```bash theme={null} curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageExport \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "organizationId": "", "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"}, "groupBy": "CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY" }' ``` **Response:** ```json theme={null} { "downloadUrl": "https://app.gitpod.io/billing/credit-usage-export/" } ``` Then download within five minutes, sending your token: ```bash theme={null} curl -L -H "Authorization: Bearer $GITPOD_API_KEY" "$DOWNLOAD_URL" | gunzip > credit-usage.csv ``` `groupBy` is `CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY` (per-user daily summary, the default) or `CREDIT_USAGE_EXPORT_GROUP_BY_RESOURCE` (per-environment and per-conversation breakdown).