> ## 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.
# AI cost usage API
Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.
The AI cost usage API exposes the BYOK (bring-your-own-key) spend data behind **Settings → Cost & Budgets**: organization totals, per-team and per-user attribution with budgets, and a daily time series. Use it to export AI spend to finance tools, find your top spenders, or track budget utilization.
All four endpoints report BYOK token spend only. Usage from Ona Intelligence (Ona-managed models) is not included, and the `credits` field is never populated. For budget concepts, see [User budgets](/ona/billing/user-budgets).
## 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 |
| ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
| **BYOK** (your own provider keys) | Spend in your billing currency, via BYOK rate cards | **This API** |
| **Ona Intelligence** (Ona-managed models) | Credits (OCUs) consumed as you use environments and AI | **[Ona Intelligence usage API](/ona/billing/ona-intelligence-usage-api)** |
**Not sure which applies to you?** Open **Settings → Cost & Budgets**: if usage is shown as **spend in a currency** (USD, EUR, or GBP), you are on BYOK (use this API); if it is shown in **credits**, you are using Ona Intelligence (use the Ona Intelligence usage API). The APIs also tell you directly: these cost endpoints return empty usage for organizations on Ona Intelligence, and the Ona Intelligence usage API returns `FAILED_PRECONDITION` with `enterprise credit usage is not enabled` for BYOK-only organizations.
## 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 by setting `filter.subject` to themselves on the per-user endpoints.
## 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` | Yes | `startTime` and `endTime` as RFC-3339 timestamps. Both dates are inclusive and the range must not exceed 31 days. Time-of-day is ignored; dates are truncated to midnight in the request timezone. |
| `timezone` | No | IANA timezone name used to bucket usage (for example `Europe/London`). Defaults to `UTC`. |
| `pagination` | List endpoints | `pageSize` and `token` for paging through results. |
Responses follow three conventions:
* Costs are reported as `costMicrounits`: millionths of the billing `currency` unit, so `"84500000"` with `BILLING_CURRENCY_USD` is \$84.50. Currencies are `BILLING_CURRENCY_USD`, `BILLING_CURRENCY_EUR`, or `BILLING_CURRENCY_GBP`.
* 64-bit integer fields (costs, token counts, limits) are returned as JSON strings, per protobuf JSON encoding. Parse them as integers.
* `calculatedAt` is the time through which usage has been calculated. Usage after that timestamp may still be processing, and fields with zero values are omitted from responses.
## Organization usage summary
Returns organization-wide spend and token counts for the date range, the monthly budget when one applies, and a per-model breakdown. Usage that no configured BYOK rate matched is reported separately as `unpricedUsage`.
**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageSummary`
**Request:**
```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageSummary \
-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}
{
"calculatedAt": "2026-07-09T11:58:02Z",
"usage": {
"costMicrounits": "84500000",
"currency": "BILLING_CURRENCY_USD",
"tokens": {
"inputTokens": "48200000",
"outputTokens": "6100000",
"cacheTokens": "310400000",
"totalTokens": "364700000"
}
},
"budget": {
"source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION",
"monthlyCostLimitMicrounits": "250000000",
"currency": "BILLING_CURRENCY_USD",
"monthToDateUsage": {
"costMicrounits": "84500000",
"currency": "BILLING_CURRENCY_USD"
},
"utilizationPercent": 33.8
},
"usageByModel": [
{
"model": "claude-opus-4-8",
"usage": {
"costMicrounits": "61200000",
"currency": "BILLING_CURRENCY_USD",
"tokens": { "inputTokens": "31500000", "outputTokens": "4400000", "cacheTokens": "228000000", "totalTokens": "263900000" }
},
"usageByTokenType": [
{ "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_INPUT", "usage": { "costMicrounits": "18900000", "currency": "BILLING_CURRENCY_USD" } },
{ "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT", "usage": { "costMicrounits": "26400000", "currency": "BILLING_CURRENCY_USD" } },
{ "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ", "usage": { "costMicrounits": "15900000", "currency": "BILLING_CURRENCY_USD" } }
]
}
]
}
```
`budget` is unset when no monthly budget applies to the organization. Token types are `BYOK_RATE_CARD_TOKEN_TYPE_INPUT`, `BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT`, `BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ`, and `BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE`.
## Per-team usage
Returns spend per team, with each team's monthly budget when one applies. Filter to specific teams with `filter.teamIds` (up to 100).
**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage`
**Request:**
```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage \
-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"},
"pagination": {"pageSize": 50}
}'
```
**Response:**
```json theme={null}
{
"pagination": {},
"calculatedAt": "2026-07-09T11:58:02Z",
"teamUsage": [
{
"teamId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
"displayName": "Platform",
"usage": {
"costMicrounits": "31800000",
"currency": "BILLING_CURRENCY_USD",
"tokens": { "inputTokens": "18400000", "outputTokens": "2300000", "cacheTokens": "119000000", "totalTokens": "139700000" }
},
"budget": {
"source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM",
"monthlyCostLimitMicrounits": "50000000",
"currency": "BILLING_CURRENCY_USD",
"utilizationPercent": 63.6
}
}
]
}
```
## Per-user usage
Returns spend for each user and service account with attributed usage, 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.
Budget fields (`monthToDateUsage`, `utilizationPercent`, `overBudget`) 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.
**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage`
**Request** (top spenders first):
```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage \
-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"},
"sort": {"field": "SORT_FIELD_USAGE", "order": "SORT_ORDER_DESC"},
"pagination": {"pageSize": 50}
}'
```
**Response:**
```json theme={null}
{
"pagination": {},
"totalCount": 24,
"calculatedAt": "2026-07-09T11:58:02Z",
"userUsage": [
{
"userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
"displayName": "Ada Lovelace",
"monthToDateUsage": {
"costMicrounits": "9400000",
"currency": "BILLING_CURRENCY_USD",
"tokens": { "inputTokens": "5200000", "outputTokens": "700000", "cacheTokens": "34100000", "totalTokens": "40000000" }
},
"monthlyCostLimitMicrounits": "10000000",
"currency": "BILLING_CURRENCY_USD",
"budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION",
"utilizationPercent": 94,
"overBudget": false,
"isServiceAccount": false
}
]
}
```
Sort fields: `SORT_FIELD_USAGE` (default, spend), `SORT_FIELD_DISPLAY_NAME`, `SORT_FIELD_BUDGET`, `SORT_FIELD_BUDGET_USED`. Subjects without a budget sort last on the budget fields. `noCap` is true for subjects explicitly exempted from budget limits.
To restrict the list to one user or service account:
```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage \
-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"}}
}'
```
## Daily time series
Returns one entry per day with spend totals and per-user, per-team, and per-model breakdowns. Per-user entries cover the top spenders, with the rest grouped into an "Others" bucket (empty `userId`).
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.
**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries`
**Request:**
```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $GITPOD_API_KEY" \
-d '{
"organizationId": "",
"dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-07T00:00:00Z"},
"timezone": "Europe/London"
}'
```
**Response:**
```json theme={null}
{
"calculatedAt": "2026-07-09T11:58:02Z",
"dailyUsage": [
{
"date": "2026-06-01T00:00:00Z",
"usage": {
"costMicrounits": "2900000",
"currency": "BILLING_CURRENCY_USD",
"tokens": { "inputTokens": "1600000", "outputTokens": "210000", "cacheTokens": "10400000", "totalTokens": "12210000" }
},
"userUsage": [
{ "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "usage": { "costMicrounits": "1200000", "currency": "BILLING_CURRENCY_USD" } },
{ "userId": "", "displayName": "Others", "usage": { "costMicrounits": "1700000", "currency": "BILLING_CURRENCY_USD" } }
],
"teamUsage": [
{ "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047", "displayName": "Platform", "usage": { "costMicrounits": "1100000", "currency": "BILLING_CURRENCY_USD" } }
],
"usageByModel": [
{ "model": "claude-opus-4-8", "usage": { "costMicrounits": "2100000", "currency": "BILLING_CURRENCY_USD" } }
]
}
]
}
```