---
title: "Ranks the period's biggest consumers"
method: GET
path: "/apiops/projects/{projectName}/usage/top"
tags: ["UsageRanking"]
---

# Ranks the period's biggest consumers

`GET /apiops/projects/{projectName}/usage/top`

## Request

- Base URL: `http://167.86.118.166:32080`
- URL: `http://167.86.118.166:32080/apiops/projects/{projectName}/usage/top`
- Auth: none declared
- TypeScript: <https://skmtc.dev/apinizer/apis/apinizer-management-apis/docs/apiops/projects/:projectName/usage/top/get.ts> (a function with typed inputs; its response is checked against the schema)

Orders one dimension (consumers, applications, api-clients, models or api-proxies) by one metric (tokens, cost or requests) and gives each row its share of the period total. The total is summed over EVERY matching row, including rows the limit cut off, so the shares of a truncated answer add up to less than 100 instead of being renormalised. Consumers, models and api-proxies are answered from the daily AI usage rollup; applications and api-clients from the traffic log, which is bounded by its retention. dataSource states which one was used.

## Path parameters

- `projectName` string, required

## Query parameters

- `dimension` string, required
- `metric` string
- `organization` string
- `from` string
- `to` string
- `model` string
- `environmentName` string
- `limit` integer

## Response `200`

successful operation!

- ApiOpsUsageRankingDTO: Ranked consumption of one dimension for a period, with each row's share of the total.
  - `dimension` string: The ranked dimension, as asked for.
  - `metric` string: The metric rows are ordered and shared out by.
  - `unit` string: Unit of value and total.
  - `period` Period: Requested and effective period, always UTC.
    - `from` string
    - `to` string
    - `effectiveFrom` string: from, rounded down to the UTC day start when a day-grained source was read.
    - `effectiveTo` string: to, rounded up to the end of its UTC day when a day-grained source was read.
    - `timeZone` string
  - `filters` Filters: Applied filters.
    - `model` string: Exact LLM model id the report was narrowed to, or null.
    - `environmentName` string: Environment name the traffic-log blocks were narrowed to, or null for every environment of the project.
    - `environmentApplied` boolean: False when environmentName could not be applied to a block because its source carries no environment dimension.
  - `dataSource` string: ROLLUP_DAILY or TRAFFIC_LOG — which source produced these numbers.
  - `freshness` string: How fresh the source is: hourly for the rollup, near-real-time for the traffic log.
  - `total` number: The metric summed over EVERY matching row, including rows the limit cut off.
  - `limit` integer: Rows the answer may carry, as applied.
  - `truncated` boolean: True when the dimension has more rows than the answer carries.
  - `items` Row[]: The ranked rows, biggest first.
    - `key` string: The child's portable key: consumerKey or apiClientKey.
    - `name` string: Display name.
    - `family` 'AI_TOKEN' | 'AI_COST' | 'REQUEST_QUOTA': Which ceiling this row describes.
    - `unit` 'TOKENS' | 'USD' | 'REQUESTS': Unit of limit/consumed/remaining.
    - `window` string: The quota window.
    - `limit` number: The ceiling. Null when the counter has none.
    - `consumed` number: Spent so far in this window.
    - `remaining` number: limit - consumed, never negative. Null when there is no ceiling.
    - `percent` number, double: Percentage of the ceiling used. Null when there is no ceiling.
    - `windowStartsAt` string: When the window opened.
    - `resetsAt` string: When the window resets.
    - `assignmentKey` string: Portable key of the limit assignment behind this counter.
    - `planKey` string: Portable key of the limit plan behind this counter.
    - `source` 'TYPED' | 'LEGACY_BUDGET' | 'POLICY': Where the ceiling comes from.
    - `status` 'OK' | 'WARNING' | 'EXCEEDED' | 'NO_BUDGET': OK, WARNING at 80% or more, EXCEEDED at 100% or more, NO_BUDGET when there is no ceiling.
  - `partial` boolean: True when at least one source could not be read; the answer is still 200 with what was readable.
  - `unavailableEnvironments` string[]: Names of the environments whose traffic log could not be read.
  - `notes` string[]: Machine-readable notes explaining zero, missing or unattributed numbers.

## Other responses

- `400`: Unknown dimension or metric, invalid period, or the platform (admin) project.
- `401`: not authorized for this operation!

## Changes

- **2026-10-20** `d1a546deccf0`: 8 breaking
  - removed the enum value `api-clients` from the `query` request parameter `dimension`
  - removed the enum value `api-proxies` from the `query` request parameter `dimension`
  - removed the enum value `applications` from the `query` request parameter `dimension`
  - removed the enum value `consumers` from the `query` request parameter `dimension`
  - …4 more
  - …this revision’s changelog is incomplete
- **2026-09-12** `90cf59a80235`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/apinizer/apis/apinizer-management-apis/changes/apiops/projects/:projectName/usage/top/get.md)

---

[API](https://skmtc.dev/apinizer/apis/apinizer-management-apis.md) - [All operations](https://skmtc.dev/apinizer/apis/apinizer-management-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/apinizer/apis/apinizer-management-apis/revisions/e083046b24cd?raw)