---
title: "InsertUsageEvents"
method: POST
path: "/gitpod.v1.BillingService/InsertUsageEvents"
tags: ["gitpod.v1.BillingService"]
---

# InsertUsageEvents

`POST /gitpod.v1.BillingService/InsertUsageEvents`

Inserts usage events from an external source (e.g., backfilling missing
 LLM token usage from a provider console export). Internal admin operation.

## Request body

- GitpodV1InsertUsageEventsRequest
  - `events` GitpodV1UsageEventInput[] — Events to insert.
    - `eventName` string — Must be a known event type: "environment_usage" or "llm_usage".
    - `organizationId` string, uuid
    - `payloadJson` string — JSON-encoded payload metadata. Validated per event_name by the service.
    - `timestamp` string — Unix epoch seconds. Raw int64 (not google.protobuf.Timestamp) to match the storage model and allow direct CSV round-tripping.
    - `userId` string, nullable
    - `value` string
  - `ignoreAgeCheck` boolean — If true, allow events with timestamps older than 35 days. By default, old events are rejected because Stripe cannot accept them.
  - `reason` string — Why these events are being inserted (stored in audit log and event payload).

## Response `200`

Success

- GitpodV1InsertUsageEventsResponse
  - `errorCount` integer
  - `insertedCount` integer — Summary counts.
  - `results` GitpodV1UsageEventInsertResult[] — One result per input event, in the same order as the request. Each result echoes the original input fields plus status columns, so the CLI can write the response directly to stdout as CSV.
    - `eventName` string
    - `idempotencyKey` string — Generated idempotency key (empty for validation errors before key generation).
    - `message` string — Error/skip reason (empty for status "ok").
    - `organizationId` string — Original input fields echoed back.
    - `payloadJson` string
    - `status` string — "ok", "skipped", or "error".
    - `timestamp` string — Unix epoch seconds (echoed from input).
    - `userId` string
    - `value` string
  - `skippedCount` integer

## Other responses

- `default` — Error

---

[API](https://skmtc.net/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.net/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/versions/44d50c2ac284/schema)