--- title: "Usage of one consumer" method: GET path: "/apiops/projects/{projectName}/consumers/{consumerKey}/usage" tags: ["UsageReport"] --- # Usage of one consumer `GET /apiops/projects/{projectName}/consumers/{consumerKey}/usage` ## Request - Base URL: `http://167.86.118.166:32080` - URL: `http://167.86.118.166:32080/apiops/projects/{projectName}/consumers/{consumerKey}/usage` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Token, cost, traffic and live budget figures for the consumer addressed by its consumer key. ## Path parameters - `projectName` string, required - `consumerKey` string, required ## Query parameters - `from` string - `to` string - `model` string - `environmentName` string ## Response `200` successful operation! - ApiOpsUsageReportDTO: Token / cost / request consumption of one subject for a period, plus its live quota budgets. - `scope` Scope: The subject of the report. - `type` 'ORGANIZATION' | 'CONSUMER' | 'APPLICATION' | 'API_CLIENT' | 'API_PROXY' - `key` string: The subject's stable key: organization code, consumerKey, applicationKey, apiClientKey or api proxy name. - `name` string: Display name of the subject. - `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. - `ai` Ai: AI token and cost consumption. - `dataSource` 'ROLLUP_DAILY' | 'TRAFFIC_LOG': ROLLUP_DAILY or TRAFFIC_LOG. - `granularity` 'DAY' | 'EXACT': DAY for the rollup, EXACT for the traffic log. - `freshness` 'hourly' | 'near-real-time': How far behind the source runs. - `totals` Totals: Summed consumption. - `tokenInput` integer - `tokenOutput` integer - `tokenCached` integer - `tokenTotal` integer: tokenInput + tokenOutput + tokenCached. - `costUsd` number: Cost in US dollars. - `requests` integer - `failedRequests` integer - `byModel` ModelRow[]: Per-model breakdown, biggest first, at most 200 rows. - `provider` string: LLM provider code, when the source carries it. - `model` string: LLM model id, e.g. gpt-5. - `tokenInput` integer - `tokenOutput` integer - `tokenCached` integer - `tokenTotal` integer - `costUsd` number - `requests` integer - `aiLicensed` boolean: Whether the AI Gateway module is licensed on this installation. Informational only — the blocks below are answered either way. - `traffic` Traffic: Gateway traffic of the subject. - `dataSource` string: Always TRAFFIC_LOG. - `totalRequests` integer - `successfulRequests` integer - `blockedRequests` integer - `erroredRequests` integer - `successRatePercent` number, double: successfulRequests * 100 / totalRequests, one decimal. - `avgTimeMs` number, double: Average total gateway time in milliseconds. - `children` Children: Breakdown one level below the scope. - `type` 'CONSUMER' | 'API_CLIENT': What the rows are. - `items` ChildRow[]: At most 200 rows, biggest token total first. - `key` string: consumerKey or apiClientKey. - `name` string - `tokenTotal` integer - `costUsd` number - `requests` integer - `usagePercent` number, double: This row's share of the scope's token total, one decimal; null when the scope total is zero. The denominator is the whole scope, so the answered rows add up to less than 100% whenever rows were dropped or traffic could not be attributed to a child. - `total` integer: How many distinct rows the scope has. Exact when 'truncated' is false; a lower bound when it is true. - `truncated` boolean: True when rows were dropped: either by the 200-row answer cap, or by the source's own bucket window before the report saw them. The report is then also marked partial with the 'child-list-truncated' note. - `budgets` Budget[]: Live quota windows of the subject: limit, consumed, remaining, percent and reset time. Independent of from/to. - `family` 'AI_TOKEN' | 'AI_COST' | 'REQUEST_QUOTA' - `unit` 'TOKENS' | 'USD' | 'REQUESTS' - `window` 'ONE_HOUR' | 'ONE_DAY' | 'ONE_MONTH': Quota window length. - `dimension` Dimension: Sub-limit axis of a budget row. - `type` 'MODEL' | 'PROVIDER' - `ref` string: The model id (MODEL) or the provider reference (PROVIDER). - `limit` number: The ceiling, in unit. Null when the counter has no ceiling or the row is a POLICY summary. - `consumed` number: Consumed so far in this window, in unit. Null on a POLICY summary row. - `remaining` number: max(limit - consumed, 0). Null when limit or consumed is null. - `usagePercent` number, double: consumed * 100 / limit, one decimal. - `windowStartsAt` string - `resetsAt` string: When the window closes and the counter resets. - `assignmentKey` string: Public handle of the limit assignment this counter accrues under, when there is one. - `planKey` string: Key of the limit plan the assignment references, when there is one. - `source` 'TYPED' | 'LEGACY_BUDGET' | 'POLICY' - `budgetsAsOf` string: How fresh the budget rows are (the quota snapshot's last sync, about one minute behind the gateway). - `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 or missing numbers. ## Other responses - `400`: Invalid period, or the platform (admin) project. - `401`: not authorized for this operation! ## Changes - **2026-09-11** `30660b2166db`: 1 info - endpoint added [Operation history](https://skmtc.dev/apinizer/apis/apinizer-management-apis/changes/apiops/projects/:projectName/consumers/:consumerKey/usage/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)