List usage events · Ownrecord docs

Lists the brand's usage events in the mode of the request, newest recorded first.

customerId, meter: one customer's or one meter's events;
occurredFrom (inclusive) and occurredTo (exclusive): when the usage happened (ISO 8601 instants);
late=true: only late usage (it happened in a period that was already invoiced), late=false: the others.

Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

At a glance

REST: GET /api/v1/usage_events
MCP tool: usage_events_list
Operation ID: usage_events.list
Scope: Brand
Permission: usage:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the usage:read scope
Since: M5

Request

Query parameters

Field	Type	Required	Description
`limit`	integer (1 to 100)	No
`starting_after`	`uev_…` ID	No
`customerId`	`cus_…` ID	No	Only this customer's events.
`meter`	string	No	Only this meter's events.
`occurredFrom`	date-time	No	Events that happened at or after this instant.
`occurredTo`	date-time	No	Events that happened before this instant.
`late`	string	No	`true`: only late events (they happened in a period that was already invoiced); `false`: only the others.

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`uev_…` ID
`data[].object`	`"usage_event"`
`data[].brandId`	`brd_…` ID
`data[].livemode`	boolean
`data[].customerId`	`cus_…` ID
`data[].subscriptionItemId`	string or null
`data[].meter`	string
`data[].quantity`	integer string	How much was used (may be negative).
`data[].occurredAt`	date-time
`data[].attributes`	object
`data[].idempotencyKey`	string
`data[].late`	boolean	The usage happened in a period that was already invoiced: it is billed on the next invoice as late usage.
`data[].walletId`	`wal_…` ID or null	Prepaid usage: the wallet it was paid from (a lease settle). null for usage billed in arrears.
`data[].reservationId`	string or null	Prepaid usage: the lease (`lease_…`) it was settled against. null for usage billed in arrears.
`data[].amount`	money or null	Prepaid usage: what it cost, in the wallet's currency. null for usage billed in arrears.
`data[].createdAt`	date-time	When Ownrecord recorded the event.
`has_more`	boolean
`next_cursor`	`uev_…` ID or null

Examples

A customer's API calls on one day

HTTP

GET /api/v1/usage_events?customerId=cus_01m4ty3c2b5qx7mhd9k8w6s0a1&meter=api.calls&occurredFrom=2026-10-13T00%3A00%3A00%2B02%3A00&occurredTo=2026-10-14T00%3A00%3A00%2B02%3A00&limit=2
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "uev_01m4v0d9k2j7r5t3w8x6y4z2a0",
      "object": "usage_event",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "subscriptionItemId": null,
      "meter": "api.calls",
      "quantity": "120",
      "occurredAt": "2026-10-13T09:15:00.000Z",
      "attributes": {
        "model": "large"
      },
      "idempotencyKey": "req_7f3a9c",
      "late": false,
      "walletId": null,
      "reservationId": null,
      "amount": null,
      "createdAt": "2026-10-13T09:15:02.000Z"
    },
    {
      "id": "uev_01m4v0d9k2j7r5t3w8x6y4z2a1",
      "object": "usage_event",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "subscriptionItemId": null,
      "meter": "api.calls",
      "quantity": "80",
      "occurredAt": "2026-10-13T09:14:00.000Z",
      "attributes": {},
      "idempotencyKey": "req_7f3a9b",
      "late": false,
      "walletId": null,
      "reservationId": null,
      "amount": null,
      "createdAt": "2026-10-13T09:14:01.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "uev_01m4v0d9k2j7r5t3w8x6y4z2a1"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter or the page size is malformed.	Fix the fields listed in `details.issues` and send the request again.
`permission_denied`	403	You can't read this brand's usage (`usage:read`).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

A customer's API calls on one day#

Errors#