---
title: "List Usage"
method: GET
path: "/v1/mcp/usage"
tags: ["mcp"]
---

# List Usage

`GET /v1/mcp/usage`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/mcp/usage`
- Auth: none declared

Paged list of MCP usage events for the calling org, with aggregated
stats over the same filter window.

Uses the `(org_uuid, ts DESC)` index for the range scan and one `$facet`
aggregation to return events, totals, and the three breakdown buckets in
a single round-trip. Stats reflect the full filtered set, not just the
visible page.

## Query parameters

- `from` string, date-time, nullable: ISO8601 lower bound (inclusive). Defaults to the start of the current UTC month.
- `to` string, date-time, nullable: ISO8601 upper bound (exclusive). Defaults to now.
- `cmd` string, nullable: Filter rows by command (e.g. `create_key`).
- `user` string, nullable: Filter by acting user uuid.
- `api_key` string, nullable: Filter by api-key uuid.
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- UsageReport
  - `range_from` string, date-time, required
  - `range_to` string, date-time, required
  - `events` UsageEventOut[], required
    - `ts` string, date-time, required
    - `cmd` string, required
    - `category` string, required
    - `units` integer, required
    - `duration_ms` integer, required
    - `status` integer, required
    - `user_uuid` string, nullable, required
    - `api_key_uuid` string, nullable, required
    - `args_size_bytes` integer, required
  - `total` integer, required
  - `stats` UsageStats, required
    - `total_events` integer, required
    - `total_units` integer, required
    - `by_category` CountBucket[], required
      - `label` string, required
      - `count` integer, required
    - `by_cmd` CountBucket[], required
      - `label` string, required
      - `count` integer, required
    - `by_status` CountBucket[], required
      - `label` string, required
      - `count` integer, required

## Other responses

- `422`: Validation Error

---

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