> 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. All dates are UTC calendar days and buckets are UTC-aligned; cost is USD. Rows for the current UTC 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 and API key in the company and may use both group\_by dimensions. A team API key (or a team owner's 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. A member's key reaches only that member's own keys. Any team\_id, api\_key\_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.

```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"]},"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 and image tokens (input + output + cache writes + cache reads + image input + image output + image cache reads). 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_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_total","cost_total"]},"UsageItem":{"allOf":[{"type":"object","properties":{"date":{"type":"string","description":"Bucket start: UTC day `YYYY-MM-DD`, or UTC hour start in RFC3339 (`2026-08-09T13:00:00Z`) 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 or hour).","items":{"$ref":"#/components/schemas/UsageItem"}}},"required":["dimensions","totals"]},"UsageGroupDimensions":{"type":"object","description":"Exactly one id/name 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"}}}}},"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. All dates are UTC calendar days and buckets are UTC-aligned; cost is USD. Rows for the current UTC 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 and API key in the company and may use both group_by dimensions. A team API key (or a team owner's 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. A member's key reaches only that member's own keys. Any team_id, api_key_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.","parameters":[{"name":"from","in":"query","required":false,"description":"Inclusive range start (UTC), YYYY-MM-DD. 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 (UTC), YYYY-MM-DD. Defaults to today (UTC); must not be in the future.","schema":{"type":"string","format":"date"}},{"name":"granularity","in":"query","required":false,"description":"`day` — one zero-filled row per UTC day; `hour` — one zero-filled row per UTC hour up to the current hour, future hours omitted (range capped at 7 days); `total` — range totals only.","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.","schema":{"type":"string","enum":["team","api_key"]}},{"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":"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","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.