---
title: "POST /v1/events.list"
method: POST
path: "/v1/events.list"
tags: ["events"]
---

# POST /v1/events.list

`POST /v1/events.list`

List usage events for your organization. Filter by customer, feature, or time range.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `start_cursor` string — Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.
  - `limit` integer — Number of items to return. Default 50, hard ceiling 5000.
  - `customer_id` string — Filter events by customer ID
  - `entity_id` string — Filter events by entity ID (e.g., per-seat or per-resource)
  - `feature_id` union — Filter by specific feature ID(s)
    - string
    - string[]
  - `custom_range` object — Filter events by time range
    - `start` number — Filter events after this timestamp (epoch milliseconds)
    - `end` number — Filter events before this timestamp (epoch milliseconds)

## Response `200`

OK

- object
  - `list` object[], required — Items for current page.
    - `id` string, required — Event ID (KSUID)
    - `timestamp` number, required — Event timestamp (epoch milliseconds)
    - `feature_id` string, required — ID of the feature that the event belongs to
    - `customer_id` string, required — Customer identifier
    - `value` number, required — Event value/count
    - `properties` object, required — Event properties (JSON)
    - `deductions` object[], nullable, required — Per-balance breakdown of what this event deducted. Null for events ingested before deductions were tracked; an empty array means the event was accepted but no balance moved.
      - `balance_id` string, required — ID of the underlying balance row that was deducted from (customer_entitlement or rollover).
      - `feature_id` string, required — The feature this balance belongs to.
      - `plan_id` string, nullable, required — ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
      - `reset` object, nullable, required — Reset configuration for the balance this deduction came from, or null if the balance doesn't reset.
        - `interval` union, required — The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
          - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
          - 'multiple'
        - `interval_count` number — Number of intervals between resets (eg. 2 for bi-monthly).
        - `resets_at` number, nullable, required — Timestamp when the balance will next reset.
      - `value` number, required — Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).
  - `next_cursor` string, nullable, required — Opaque cursor for the next page. Null when there are no more results.

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/revisions/29536933c0dc/schema)