APapinizer
UsageRanking

Ranks the period's biggest consumers

Changed on

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.

get/apiops/projects/{projectName}/usage/top

Request

Path parameters

projectNamestring required

Project name

Query parameters

dimensionstring required

What to rank: consumers, applications, api-clients, models or api-proxies.

metricstring

What to rank by: tokens (default), cost or requests.

organizationstring

Consumer organization code the ranking is narrowed to.

fromstring

Start of the period, ISO-8601 UTC (2026-08-01, 2026-08-01T00:00:00Z or an offset date-time). Defaults to 30 days before 'to'.

tostring

End of the period, ISO-8601 UTC. Defaults to now. The period may not be inverted or wider than 366 days.

modelstring

Exact LLM model id (e.g. gpt-5). Narrows the answer to that model's requests.

environmentNamestring

Environment name. Defaults to every environment of the project. Applies to traffic-log answers only; filters.environmentApplied reports whether it took effect.

limitinteger

Rows the answer may carry. Default 50, at most 500; truncated states whether rows were left out.

Response

successful operation!

dimensionstring

The ranked dimension, as asked for.

metricstring

The metric rows are ordered and shared out by.

unitstring

Unit of value and total.

dataSourcestring

ROLLUP_DAILY or TRAFFIC_LOG — which source produced these numbers.

freshnessstring

How fresh the source is: hourly for the rollup, near-real-time for the traffic log.

totalnumber

The metric summed over EVERY matching row, including rows the limit cut off.

limitinteger

Rows the answer may carry, as applied.

truncatedboolean

True when the dimension has more rows than the answer carries.

partialboolean

True when at least one source could not be read; the answer is still 200 with what was readable.

unavailableEnvironmentsstring[]

Names of the environments whose traffic log could not be read.

notesstring[]

Machine-readable notes explaining zero, missing or unattributed numbers.

Example response

{
  "dimension": "consumers",
  "metric": "cost",
  "unit": "USD",
  "period": {
    "from": "2026-08-12T00:00:00Z",
    "to": "2026-09-11T00:00:00Z",
    "timeZone": "UTC"
  },
  "limit": 50,
  "items": [
    {
      "window": "ONE_MONTH"
    }
  ]
}

Changes

  • d1a546deccf0Revision changes
    • breaking

      removed the enum value api-clients from the query request parameter dimension

    • breaking

      removed the enum value api-proxies from the query request parameter dimension

    • breaking

      removed the enum value applications from the query request parameter dimension

    • breaking

      removed the enum value consumers from the query request parameter dimension

    • breaking

      removed the enum value cost from the query request parameter metric

    • breaking

      removed the enum value models from the query request parameter dimension

    • breaking

      removed the enum value requests from the query request parameter metric

    • breaking

      removed the enum value tokens from the query request parameter metric

    This list may be incomplete.

  • 90cf59a80235Revision changes
    • info

      endpoint added