---
title: "Aggregate Usage"
method: GET
path: "/api/v1/admin/aggregate/usage"
tags: ["admin"]
---

# Aggregate Usage

`GET /api/v1/admin/aggregate/usage`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/admin/aggregate/usage`
- Auth: API key in header `X-Admin-Key`

Platform-wide usage aggregated across ALL organizations for the
last N days (default 7).

Powers the portal admin dashboard's "platform usage" card. v1 is
operational-only: reads/writes/feedbacks/queries, distinct active
keys, distinct organizations, and the top 10 orgs by query volume.

Response notes for consumers: the top-level totals cover ALL
organizations, whereas `top_orgs_by_queries` is only the TOP 10 — do
NOT sum it to derive the platform total (use `total_queries`). The
`daily` array is ordered newest-first by date and omits days with no
activity (gaps mean zero), so its length may be < `days`.

`days` is validated to `[1, 90]` at the FastAPI layer via `Query`
(HTTP 422 before any DB work). The window itself is computed in
Postgres as `CURRENT_DATE - make_interval(days => $1)` with the day
count bound as a parameter — never string-interpolated. The only
interpolated token in any of these queries is `{schema}`, which is a
validated SQL identifier from settings (`validate_sql_identifier`),
not request input.

## Query parameters

- `days` integer

## Response `200`

Successful Response

- AggregateUsageResponse
  - `period` AggregateUsagePeriod, required
    - `start_date` string, required
    - `end_date` string, required
    - `days` integer, required
  - `total_reads` integer, required
  - `total_writes` integer, required
  - `total_feedbacks` integer, required
  - `total_queries` integer, required
  - `daily` AggregateUsageDay[], required
    - `date` string, required
    - `reads` integer, required
    - `writes` integer, required
    - `feedbacks` integer, required
    - `total` integer, required
  - `distinct_active_keys` integer, required
  - `distinct_organizations` integer, required
  - `top_orgs_by_queries` AggregateTopOrg[], required
    - `org_id` string, required
    - `total_queries` integer, required
    - `reads` integer, required
    - `writes` integer, required
    - `feedbacks` integer, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Service unavailable

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)