# List usage events

> The usage_events.list operation: GET /api/v1/usage_events in the REST API and the usage_events_list tool in the MCP server.

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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).