# Usage tools

> MCP tools for Usage: usage_aggregates_list.

- `usage_aggregates_list`: List daily usage

## `usage_aggregates_list`

**List daily usage.** Operation [`usage.aggregates.list`](https://ownrecord.io/docs/reference/usage-aggregates-list.md) · Brand level · permission `usage:read` · risk tier `read` · since M5

Lists the brand's daily usage aggregates in the mode of the request: one per customer, meter, day and
attribute set, with the day's sum (`quantity`), event count, largest quantity (`max`) and last event
(`last`). Days are calendar days in the entity's time zone; `start` and `end` are the instants each spans.
Late usage counts on the day it happened.

- `customerId`, `meter`: one customer's or one meter's usage;
- `from`, `to`: the first and last day, inclusive (YYYY-MM-DD).

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

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type          | Required | Description                                                                                                                              |
| ---------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`          | integer       | no       | (1–100)                                                                                                                                  |
| `starting_after` | ID (`uagg_…`) | no       | –                                                                                                                                        |
| `customerId`     | ID (`cus_…`)  | no       | Only this customer's usage.                                                                                                              |
| `meter`          | string        | no       | Only this meter's usage. (at most 100 characters)                                                                                        |
| `from`           | string        | no       | The first day, inclusive (YYYY-MM-DD, in the entity's time zone).                                                                        |
| `to`             | string        | no       | The last day, inclusive.                                                                                                                 |
| `entity_id`      | ID (`ent_…`)  | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`       | ID (`brd_…`)  | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter, the page size or the cursor is malformed.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this brand's usage (`usage:read`).

### Example

**A customer's API calls in October**

Arguments:

```json
{
  "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
  "meter": "api.calls",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "limit": 2,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a2",
      "object": "usage_aggregate",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "meter": "api.calls",
      "period": "2026-10-13",
      "timeZone": "Europe/Zagreb",
      "start": "2026-10-12T22:00:00.000Z",
      "end": "2026-10-13T22:00:00.000Z",
      "attributes": {
        "model": "large"
      },
      "quantity": "4230",
      "eventCount": 37,
      "max": "640",
      "last": {
        "quantity": "120",
        "occurredAt": "2026-10-13T21:40:00.000Z",
        "eventId": "uev_01m4v0d9k2j7r5t3w8x6y4z2a1"
      },
      "amounts": [],
      "updatedAt": "2026-10-13T21:40:01.000Z"
    },
    {
      "id": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a3",
      "object": "usage_aggregate",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "meter": "api.calls",
      "period": "2026-10-12",
      "timeZone": "Europe/Zagreb",
      "start": "2026-10-11T22:00:00.000Z",
      "end": "2026-10-12T22:00:00.000Z",
      "attributes": {
        "model": "large"
      },
      "quantity": "3910",
      "eventCount": 31,
      "max": "512",
      "last": {
        "quantity": "64",
        "occurredAt": "2026-10-12T20:05:00.000Z",
        "eventId": "uev_01m4v0d9k2j7r5t3w8x6y4z2a0"
      },
      "amounts": [],
      "updatedAt": "2026-10-12T20:05:01.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a3"
}
```