> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/usage.md).

# Usage

Query metered LLM consumption (requests, tokens, cost).

## Get usage report

> Returns metered LLM consumption (requests, tokens, cost) for the caller's scope as a daily or hourly UTC series or range totals, optionally grouped by team or API key. A bare call returns the last 30 days for the calling key's scope (last 7 days with granularity=hour). Range caps: 90 days; 31 days when group\_by is combined with granularity=day; 7 days when granularity=hour. Dates are calendar days in the requested \`timezone\` (UTC by default) and buckets are aligned to that timezone's day and hour boundaries; cost is USD. Rows for the current day (or hour) are partial; hourly series end at the current hour, future hours are omitted.\
> \
> Access levels gate how you may slice. A company owner's key reaches every team, API key, and user in the company and may use all group\_by dimensions. A team API key reaches only its own team: team\_id must name that team, api\_key\_id only keys belonging to it, and group\_by is limited to api\_key; it may not filter by user. A team owner's personal key reaches its own team the same way, while a member's personal key reaches only that member's own keys; either may filter user\_id to itself alone. group\_by=user otherwise requires a company owner's key. Any team\_id, api\_key\_id, user\_id, or group\_by beyond the caller's reach fails the whole request with 403 — results are never silently truncated. Filters that match nothing within the caller's scope return zero-filled rows.\
> \
> User grouping aggregates usage attributed to a user's identity across all their API keys. Requests that carry no user identity (e.g. shared team API keys) are not attributable and count toward the \`\_\_other\_\_\` group, as does usage of users beyond the 100 highest-spending users in the window and beyond \`limit\`. order\_by ranks within those top spenders.

```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Usage","description":"Query metered LLM consumption (requests, tokens, cost)."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"responses":{"UsageResponse":{"description":"Usage report for the requested scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}}}},"ErrorResponse":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"object","title":"Detail"}},"required":["detail"]}}}}},"schemas":{"UsageReport":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","enum":["day","hour","total"]},"group_by":{"type":"string","enum":["team","api_key","user"]},"totals":{"$ref":"#/components/schemas/UsageMetrics"},"items":{"type":"array","description":"Bucketed series for the requested scope (granularity=day or hour).","items":{"$ref":"#/components/schemas/UsageItem"}},"groups":{"type":"array","description":"Present when group_by is set; ranked by order_by descending.","items":{"$ref":"#/components/schemas/UsageGroup"}},"top_models":{"type":"array","description":"Range-level top models; present when include=top_models.","items":{"$ref":"#/components/schemas/UsageTopModel"}}},"required":["from","to","granularity","totals"]},"UsageMetrics":{"type":"object","description":"Full metric set for a scope. tokens_total includes all cache, image, reasoning and audio tokens (input + output + cache writes + cache reads + image input + image output + image cache reads + reasoning + audio input + audio output). The tokens_image_* buckets are disjoint from tokens_input and tokens_cache_read. cost_total is USD and already includes image spend.","properties":{"requests":{"type":"integer","format":"int64"},"tokens_input":{"type":"integer","format":"int64"},"tokens_output":{"type":"integer","format":"int64"},"tokens_cache_write":{"type":"integer","format":"int64"},"tokens_cache_write_1h":{"type":"integer","format":"int64"},"tokens_cache_read":{"type":"integer","format":"int64"},"tokens_image_input":{"type":"integer","format":"int64","description":"Image input tokens; their own bucket, not part of tokens_input."},"tokens_image_output":{"type":"integer","format":"int64","description":"Image output tokens."},"tokens_image_cache_read":{"type":"integer","format":"int64","description":"Cached image input tokens on image generation; not part of tokens_cache_read."},"tokens_reasoning":{"type":"integer","format":"int64","description":"Reasoning tokens; not part of tokens_output. Zero for usage before 2026-10-26, when they were counted inside tokens_output."},"tokens_audio_input":{"type":"integer","format":"int64","description":"Audio input tokens; not part of tokens_input. Zero for usage before 2026-10-26, when they were counted inside tokens_input."},"tokens_audio_output":{"type":"integer","format":"int64","description":"Audio output tokens; not part of tokens_output. Zero for usage before 2026-10-26, when they were counted inside tokens_output."},"tokens_total":{"type":"integer","format":"int64"},"cost_total":{"type":"number","format":"double"}},"required":["requests","tokens_input","tokens_output","tokens_cache_write","tokens_cache_write_1h","tokens_cache_read","tokens_image_input","tokens_image_output","tokens_image_cache_read","tokens_reasoning","tokens_audio_input","tokens_audio_output","tokens_total","cost_total"]},"UsageItem":{"allOf":[{"type":"object","properties":{"date":{"type":"string","description":"Bucket start in the report `timezone`: a calendar day `YYYY-MM-DD`, or the hour start in RFC3339 with the zone's offset (`2026-08-09T13:00:00+02:00`) for granularity=hour."},"top_models":{"type":"array","description":"Present when include=top_models.","items":{"$ref":"#/components/schemas/UsageTopModel"}}},"required":["date"]},{"$ref":"#/components/schemas/UsageMetrics"}]},"UsageTopModel":{"allOf":[{"type":"object","properties":{"model":{"type":"string","description":"Model name, or `__other__` for the rollup row."}},"required":["model"]},{"$ref":"#/components/schemas/UsageMetrics"}]},"UsageGroup":{"type":"object","properties":{"dimensions":{"$ref":"#/components/schemas/UsageGroupDimensions"},"totals":{"$ref":"#/components/schemas/UsageMetrics"},"items":{"type":"array","description":"Bucketed series for this group. granularity=day: one zero-filled row per day; granularity=hour: sparse — only buckets with usage.","items":{"$ref":"#/components/schemas/UsageItem"}}},"required":["dimensions","totals"]},"UsageGroupDimensions":{"type":"object","description":"Exactly one identity pair is set, matching group_by. The synthetic rollup group uses id `__other__`.","properties":{"team_id":{"type":"string"},"team_name":{"type":"string"},"api_key_id":{"type":"string"},"api_key_name":{"type":"string"},"user_id":{"type":"string"},"user_email":{"type":"string"}}}}},"paths":{"/v1/usage":{"get":{"operationId":"get-usage-v1","tags":["Usage"],"summary":"Get usage report","description":"Returns metered LLM consumption (requests, tokens, cost) for the caller's scope as a daily or hourly UTC series or range totals, optionally grouped by team or API key. A bare call returns the last 30 days for the calling key's scope (last 7 days with granularity=hour). Range caps: 90 days; 31 days when group_by is combined with granularity=day; 7 days when granularity=hour. Dates are calendar days in the requested `timezone` (UTC by default) and buckets are aligned to that timezone's day and hour boundaries; cost is USD. Rows for the current day (or hour) are partial; hourly series end at the current hour, future hours are omitted.\n\nAccess levels gate how you may slice. A company owner's key reaches every team, API key, and user in the company and may use all group_by dimensions. A team API key reaches only its own team: team_id must name that team, api_key_id only keys belonging to it, and group_by is limited to api_key; it may not filter by user. A team owner's personal key reaches its own team the same way, while a member's personal key reaches only that member's own keys; either may filter user_id to itself alone. group_by=user otherwise requires a company owner's key. Any team_id, api_key_id, user_id, or group_by beyond the caller's reach fails the whole request with 403 — results are never silently truncated. Filters that match nothing within the caller's scope return zero-filled rows.\n\nUser grouping aggregates usage attributed to a user's identity across all their API keys. Requests that carry no user identity (e.g. shared team API keys) are not attributable and count toward the `__other__` group, as does usage of users beyond the 100 highest-spending users in the window and beyond `limit`. order_by ranks within those top spenders.","parameters":[{"name":"from","in":"query","required":false,"description":"Inclusive range start, YYYY-MM-DD, a calendar date in `timezone`. Defaults to `to` minus 30 days (minus 6 days when granularity=hour).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Inclusive range end, YYYY-MM-DD, a calendar date in `timezone`. Defaults to today there; must not be in the future.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"[IANA timezone](https://timeapi.io/documentation/iana-timezones) the report is expressed in, e.g. `Europe/Warsaw`. Defaults to `UTC`. `from` and `to` are read as calendar dates in this timezone, `to` defaults to today there, and every date and hourly timestamp in the response is rendered with that timezone's offset. Unknown names are rejected with 400.","schema":{"type":"string"}},{"name":"granularity","in":"query","required":false,"description":"`day` — one zero-filled row per calendar day in `timezone`; `hour` — one zero-filled row per hour in `timezone` up to the current hour, future hours omitted (range capped at 7 days); `total` — range totals only. A range ending today yields a variable-length hourly series (up to the current hour); request a fully-past range for a fixed 24-rows-per-day series. This describes the top-level items; group items are zero-filled for `day` but sparse for `hour` (only buckets with usage).","schema":{"type":"string","enum":["day","hour","total"],"default":"day"}},{"name":"group_by","in":"query","required":false,"description":"Adds a `groups` array sliced by the given dimension. `user` requires a company owner's key.","schema":{"type":"string","enum":["team","api_key","user"]}},{"name":"team_id","in":"query","required":false,"description":"Restrict to these teams (repeatable, max 100).","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"api_key_id","in":"query","required":false,"description":"Restrict to these API keys (repeatable, max 100). Combines with team_id as AND — a key outside the filtered teams yields zero-filled rows, not an error.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"user_id","in":"query","required":false,"description":"Restrict to usage attributed to these users (repeatable, max 100). Company owner's key required; a member's key may name only itself. Combines with other filters as AND.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"order_by","in":"query","required":false,"description":"Ranks groups descending; only meaningful with group_by.","schema":{"type":"string","enum":["cost_total","tokens_total","requests"],"default":"cost_total"}},{"name":"limit","in":"query","required":false,"description":"Max groups returned (1-100), ranked by order_by.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"default":25}},{"name":"include_other","in":"query","required":false,"description":"When limit truncates, append one synthetic `__other__` group aggregating the rest so group totals reconcile with response totals.","schema":{"type":"boolean","default":true}},{"name":"include_customer_key_usage","in":"query","required":false,"description":"Count requests served with the company's own provider credentials (bring your own key). Set to false to report only usage served by nexos providers.","schema":{"type":"boolean","default":true}},{"name":"include","in":"query","required":false,"description":"`top_models` — adds range-level and per-day top-models breakdowns. Each day ranks its own top models independently; the `__other__` row aggregates the rest so model rows reconcile with day and range totals.","schema":{"type":"array","items":{"type":"string","enum":["top_models"]}}},{"name":"top_models_limit","in":"query","required":false,"description":"Max model rows (1-20); the `__other__` rollup row does not count.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":20,"default":5}},{"name":"top_models_rank_by","in":"query","required":false,"description":"Ranking dimension for top models.","schema":{"type":"string","enum":["cost_total","tokens_total","requests"],"default":"cost_total"}}],"responses":{"200":{"$ref":"#/components/responses/UsageResponse"},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexos.ai/gateway-api/usage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
