List Usage Event Details

Returns one root-level usage event per item in usage_events[]. Its metrics object is the aggregated charge-item view, with metric names emitted in ascending order. This endpoint is the best fit for audit trails, customer support views, and billing explainability.

GET /v1/projects/:project_id/usage/events/details

Authentication

Authorization: Bearer <api-key>

Requires usage read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the usage events.

Request Body

Empty. This GET endpoint accepts filters only through query parameters.

Query Parameters

Field	Required	Description
raw_event_id	No	Filter by the original raw event identity.
billing_account_id	No	Filter by the usage event’s persisted billing account ownership snapshot. Use this top-level parameter instead of filter.billing_account_id.
subject_type	No	Filter by usage subject type, for example user, organization, or agent. A non-empty top-level value overrides filter.subject_type.
subject_id	No	Filter by usage subject ID. A non-empty top-level value overrides filter.subject_id.
metric	No	Return the matching metric for one metric name.
metrics	No	Return matching metrics for any name in the list. Can be repeated or comma-separated.
filter.<key>	No	Filter by built-in dimensions or event labels, for example filter.model=gpt-4.1-mini.
start_time	No	Start time as Unix seconds.
end_time	No	End time as Unix seconds.
after_id	No	Cursor from the previous response’s next_after_id.
limit	No	Page size. Defaults to 100; maximum is 1000.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/events/details?billing_account_id=acct_org_001&subject_type=user&subject_id=user_123&start_time=1778580000&end_time=1778666400&limit=100' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "usage_events": [
    {
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "event_date": "2026-06-12",
      "occurred_at": 1781222400,
      "raw_event_id": "raw_evt_01",
      "source": "llm_gateway",
      "subject_type": "user",
      "subject_id": "user_123",
      "billing_account_id": "acct_xxx",
      "labels": {
        "provider": "openai",
        "model": "gpt-4.1-mini"
      },
      "metrics": {
        "input_tokens": {
          "value": "1200",
          "unit": "token",
          "currency": "USD",
          "amount": "0.00024"
        }
      },
      "usage_version": 42,
      "ingested_at": 1781222401,
      "processed_at": 1781222402
    }
  ],
  "next_after_id": "raw_evt_01",
  "total": 1234
}

Pagination

total is always returned: the number of events matching the same filters, independent of limit and after_id, or 0 when none match. next_after_id is returned only when another matching event exists; it is omitted on the last page, including an exactly full page. Retain all filters on subsequent pages. Count, page and next-page checks are separate queries rather than a snapshot; concurrent ingestion or revocation can change results.

When next_after_id is returned, pass it as after_id on the next request:

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/events/details?after_id=raw_evt_01&limit=100' \
  -H 'Authorization: Bearer <api-key>'

When no metric filter is supplied, the endpoint reads the complete metrics object once per event. Nested Doris VARIANT paths are normalized to flat logical names in the response; for example, tool_call → web_search is returned under the key tool_call.web_search.

billing_account_id reads the dedicated billing-account column. It does not match an event label with the same name, and filter.billing_account_id is rejected to avoid ambiguous results.

filter.subject_type and filter.subject_id remain supported when their matching top-level parameter is omitted.

Event times use Unix seconds: occurred_at is the business occurrence time and drives time-range filters; ingested_at is the raw event’s Kafka ingestion time; processed_at is successful processing persistence time. Retries and repairs preserve the original ingestion time; repairs also preserve the original processing time. Unknown historical timestamps return 0.