List Usage Events

Returns one row per processed usage event. Each event row includes labels and a compact metrics map keyed by metric name.

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

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
`usage_event_id`	No	Filter to one normalized usage event.
`raw_event_id`	No	Filter by the source raw event.
`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	Filter to events that contain one metric.
`metrics`	No	Filter to events that contain any metric 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 ID used for keyset pagination.
`limit`	No	Page size. Defaults to `100`; maximum is `1000`.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/events?billing_account_id=acct_org_001&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,
      "usage_event_id": "usage_evt_01",
      "raw_event_id": "raw_evt_01",
      "source": "llm_gateway",
      "external_event_id": "chatcmpl_123",
      "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",
          "unit_price": "0.0000002"
        },
        "output_tokens": {
          "value": "300",
          "unit": "token",
          "currency": "USD",
          "amount": "0.00024",
          "unit_price": "0.0000008"
        }
      },
      "usage_version": 42,
      "created_at": 1781222400
    }
  ]
}

Notes

Use this endpoint for event search and lightweight usage history views.
filter.subject_type and filter.subject_id remain supported when their matching top-level parameter is omitted.
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.
When no metric filter is supplied, Doris reads the complete metrics object once per event. Responses expose logical metric names as flat keys, so a nested physical VARIANT path is returned as tool_call.web_search.
Use List Usage Event Details when you also need charge item rows.