> 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 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. Range caps: 90 days, or 31 days when group\_by is combined with granularity=day. All dates are UTC calendar days; cost is USD. Rows for the current UTC day are partial.\
> \
> 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","total"]},"group_by":{"type":"string","enum":["team","api_key"]},"totals":{"$ref":"#/components/schemas/UsageMetrics"},"items":{"type":"array","description":"Daily series for the requested scope (granularity=day only).","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 tokens (input + output + cache writes + cache reads). cost_total is USD.","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_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_total","cost_total"]},"UsageItem":{"allOf":[{"type":"object","properties":{"date":{"type":"string","format":"date"},"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":"Daily series for this group (granularity=day only).","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 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. Range caps: 90 days, or 31 days when group_by is combined with granularity=day. All dates are UTC calendar days; cost is USD. Rows for the current UTC day are partial.\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.","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; `total` — range totals only.","schema":{"type":"string","enum":["day","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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.