---
title: "List usage events"
method: GET
path: "/v1/events"
tags: ["Events"]
---

# List usage events

`GET /v1/events`

## Request

- Base URL: `https://api.creem.io`
- URL: `https://api.creem.io/v1/events`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/creem/apis/creem-api/docs/v1/events/get.ts> (a function with typed inputs; its response is checked against the schema)

List the usage events your store has ingested, oldest first in ingestion order, as a forward cursor page. Filters compose: by meter (resolved to the meter's event name), by customer, and by `reference` (the `event_id` you supplied). Events are returned raw — a meter's filter clauses are not applied. Usage events are append-only, so pagination is forward-only and there is no `ending_before`.

## Query parameters

- `meter_id` string
- `customer_id` string
- `reference` string
- `limit` number
- `starting_after` string

## Response `200`

Paginated list of usage events

- UsageEventListApiResponseDto
  - `object` string, required: Object type
  - `data` UsageEventApiResponseDto[], required: Array of usage events
    - `id` string, required: Usage event ID
    - `customer_id` string, required: Customer ID
    - `event_id` string, required: Your idempotency key for this event
    - `name` string, required: Event name
    - `properties` object, required: The event's attributes — meter filters and aggregation read their keys here
    - `timestamp` string, required: When the usage occurred, on your clock (ISO 8601)
    - `created_at` string, required: When the event was ingested (ISO 8601)
    - `matched_meters` string[], required: Ids of the ACTIVE meters that consume this event name, computed at read time (an archived or later-created meter changes this answer — it is not stored with the event). An empty array means the event is not feeding any aggregation right now.
  - `has_more` boolean, required: Whether more items exist beyond this page

## Other responses

- `400`: Bad Request - Invalid input parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not Found - Resource does not exist

## Changes

- **2026-09-15** `071301350724`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/creem/apis/creem-api/changes/v1/events/get.md)

---

[API](https://skmtc.dev/creem/apis/creem-api.md) - [All operations](https://skmtc.dev/creem/apis/creem-api/llms.txt) - [OpenAPI document](https://skmtc.dev/creem/apis/creem-api/revisions/3f39a8f266c3?raw)