> ## 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 Credit Usage Export

> Returns a signed download URL for a CSV export of credit usage.

`Unary` · [`Billing`](/docs/api-reference/generated/billing/overview)

Returns a signed download URL for a CSV export of credit usage.

The URL points to an HTTP endpoint that streams gzip-compressed CSV and
is valid for five minutes. The download must be made by the same principal
that requested it, carrying its own bearer token. The export range may
cover up to a year.

For organizations without enterprise credit usage enabled (no billing
contract start date), the export instead contains BYOK cost usage with a
different column set, and groupBy=RESOURCE is rejected.

Use this method to:

* Export per-user daily credit usage for external reporting
* Export a per-environment and per-conversation resource breakdown

### Examples

* Export January's daily summary:

  ```yaml theme={null}
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  dateRange:
    startTime: "2024-01-01T00:00:00Z"
    endTime: "2024-01-31T00:00:00Z"
  groupBy: CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY
  ```

### Authorization

Requires `billing:read_usage` permission on the organization.

## Endpoint

```text theme={null}
POST /api/gitpod.v1.BillingService/GetCreditUsageExport
```

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

<CodeGroup>
  ```bash cURL theme={null}
  export ONA_HOST=https://app.ona.com
  export ONA_API_KEY=<your-token>

  curl --request POST \
    --url "$ONA_HOST/api/gitpod.v1.BillingService/GetCreditUsageExport" \
    --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": "<organization-id>"
  }'
  ```

  ```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.GetCreditUsageExportRequest(
      organization_id="<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_credit_usage_export(request)
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import { create } from "@bufbuild/protobuf";
  import { createClientFromEnv } from "@gitpod/sdk";
  import { GetCreditUsageExportRequestSchema } from "@gitpod/sdk/gitpod/v1/billing_pb";
  import { timestampFromDate } from "@bufbuild/protobuf/wkt";

  async function main() {
    const ona = createClientFromEnv();
    const request = create(GetCreditUsageExportRequestSchema, {
      organizationId: "<organization-id>",
      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.getCreditUsageExport(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.GetCreditUsageExportRequest{
  		OrganizationId: "<organization-id>",
  		DateRange: &gitpodpb.DateRange{
  			StartTime: &timestamppb.Timestamp{Seconds: 1767225600},
  			EndTime: &timestamppb.Timestamp{Seconds: 1767225600},
  		},
  	})
  	response, err := ona.Services.Billing.GetCreditUsageExport(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": "<organization-id>"
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.GetCreditUsageExportRequest`

| Field            | Type                                                                     | Required | Description                                                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationId` | string                                                                   | Yes      | Constraints: `required=true, string.uuid=true`.                                                                                                                                    |
| `dateRange`      | [DateRange](#type-gitpod-v1-date-range)                                  | Yes      | Date range to export. Both start and end dates are inclusive; time-of-day is ignored. Unlike GetCreditUsageReport, the range may cover up to a year. Constraints: `required=true`. |
| `groupBy`        | [CreditUsageExportGroupBy](#enum-gitpod-v1-credit-usage-export-group-by) | No       | How to group the export data. Defaults to DAILY\_SUMMARY.                                                                                                                          |

## Response

`gitpod.v1.GetCreditUsageExportResponse`

| Field         | Type   | Required | Description                                                                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `downloadUrl` | string | No       | Signed download URL for the CSV export. Valid for five minutes, and only for the principal that requested it. |

## Related types

<a id="type-gitpod-v1-date-range" />

<Accordion title="DateRange">
  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`.   |
</Accordion>

<a id="enum-gitpod-v1-credit-usage-export-group-by" />

<Accordion title="CreditUsageExportGroupBy">
  How to group the credit usage export data.

  | Value                                        | Number | Description                                   |
  | -------------------------------------------- | -----: | --------------------------------------------- |
  | `CREDIT_USAGE_EXPORT_GROUP_BY_UNSPECIFIED`   |      0 | Defaults to DAILY\_SUMMARY.                   |
  | `CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY` |      1 | Daily summary grouped by user.                |
  | `CREDIT_USAGE_EXPORT_GROUP_BY_RESOURCE`      |      2 | Breakdown by environment and agent execution. |
</Accordion>