> ## 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

> [!NOTE]
>
> 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](https://ona.com/docs/ona/billing/cost-usage-api.md)** |

**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](https://ona.com/docs/ona/integrations/personal-access-token.md) (acts as you) or a [service account token](https://ona.com/docs/ona/organizations/service-accounts.md) (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](https://ona.com/docs/ona/organizations/organization-roles.md#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/<Method>
```

| 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": "<your-org-id>",
       "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": "gpt-5.6-terra",
          "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": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"},
       "filter": {"subject": {"id": "<user-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": "<your-org-id>"}'
```

**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": "gpt-5.6-terra", "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": "<your-org-id>",
       "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": "gpt-5.6-terra", "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": "<your-org-id>",
       "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/<signed-token>"
}
```

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).

The export prefixes names, email addresses, and team names with an apostrophe when they start with characters that spreadsheet applications can interpret as formulas or controls. This keeps those characters from appearing at the start of an imported cell. Direct CSV parsers see the added apostrophe; identifier and numeric columns remain unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.