Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.
docs: add model grouping to cloud usage (#19069)
Devon Rifkin2476d5ead197
diff --git a/docs/api/cloud-usage.mdx b/docs/api/cloud-usage.mdxindex 9fd3cf9b0..6ea3ef4bd 100644--- a/docs/api/cloud-usage.mdx+++ b/docs/api/cloud-usage.mdx@@ -92,9 +92,158 @@ All timestamps are in UTC. Each `from` is inclusive and each `until` is exclusiv`partial` indicates whether the hour or day is still in progress, rather than whether all usage has been recorded.+## Model breakdown++Add `group_by=model` to see usage by model:++```shell+curl 'https://ollama.com/api/usage?range=7d&group_by=model' \+ -H "Authorization: Bearer $OLLAMA_API_KEY"+```++The response includes `groups` in both `totals` and every bucket.++```json Response excerpt+{+ "totals": {+ "groups": [+ {+ "model": "glm-5.3-flash",+ "request_count": 12,+ "usage_usd": 0.0132+ }+ ]+ },+ "buckets": [+ {+ "from": "2026-09-30T00:00:00Z",+ "until": "2026-10-01T00:00:00Z",+ "groups": [+ {+ "model": "glm-5.3-flash",+ "request_count": 6,+ "usage_usd": 0.0066+ }+ ]+ }+ ]+}+```++<Accordion title="Example with multiple models and buckets">++```json Response (6 empty buckets omitted)+{+ "range": "7d",+ "scope": "self",+ "granularity": "day",+ "group_by": "model",+ "from": "2026-09-24T00:00:00Z",+ "until": "2026-10-01T02:30:00Z",+ "totals": {+ "request_count": 16,+ "usage_usd": 0.0268,+ "input_tokens": 116000,+ "cached_input_tokens": 60000,+ "output_tokens": 15000,+ "groups": [+ {+ "model": "glm-5.3-flash",+ "request_count": 12,+ "usage_usd": 0.0132,+ "input_tokens": 96000,+ "cached_input_tokens": 60000,+ "output_tokens": 12000+ },+ {+ "model": "glm-5.3",+ "request_count": 2,+ "usage_usd": 0.01,+ "input_tokens": 4000,+ "cached_input_tokens": 0,+ "output_tokens": 1000+ },+ {+ "model": "gpt-oss:120b",+ "request_count": 2,+ "usage_usd": 0.0036,+ "input_tokens": 16000,+ "cached_input_tokens": 0,+ "output_tokens": 2000+ }+ ]+ },+ "buckets": [+ {+ "from": "2026-09-30T00:00:00Z",+ "until": "2026-10-01T00:00:00Z",+ "request_count": 8,+ "usage_usd": 0.0166,+ "input_tokens": 52000,+ "cached_input_tokens": 30000,+ "output_tokens": 7000,+ "groups": [+ {+ "model": "glm-5.3-flash",+ "request_count": 6,+ "usage_usd": 0.0066,+ "input_tokens": 48000,+ "cached_input_tokens": 30000,+ "output_tokens": 6000+ },+ {+ "model": "glm-5.3",+ "request_count": 2,+ "usage_usd": 0.01,+ "input_tokens": 4000,+ "cached_input_tokens": 0,+ "output_tokens": 1000+ }+ ]+ },+ {+ "from": "2026-10-01T00:00:00Z",+ "until": "2026-10-01T02:30:00Z",+ "partial": true,+ "request_count": 8,+ "usage_usd": 0.0102,+ "input_tokens": 64000,+ "cached_input_tokens": 30000,+ "output_tokens": 8000,+ "groups": [+ {+ "model": "glm-5.3-flash",+ "request_count": 6,+ "usage_usd": 0.0066,+ "input_tokens": 48000,+ "cached_input_tokens": 30000,+ "output_tokens": 6000+ },+ {+ "model": "gpt-oss:120b",+ "request_count": 2,+ "usage_usd": 0.0036,+ "input_tokens": 16000,+ "cached_input_tokens": 0,+ "output_tokens": 2000+ }+ ]+ }+ ]+}+```++</Accordion>++Currently, up to 10 groups appear under `groups`, ranked by total `usage_usd` across the range.++Every bucket uses the same selection and order. Groups with no requests in a bucket are omitted; an empty bucket has `groups: []`.++Additional groups are combined under `remainder`, omitted when empty. Totals always include all usage.+<Accordion title="Legacy plans">-For legacy plans, only request counts are available. If a bucket or total includes legacy requests, cost and token counts are omitted.+For usage that includes requests from legacy plans, only request counts are available. If the range includes legacy requests, groups are ranked by request count instead of cost.</Accordion>@@ -115,6 +264,6 @@ curl 'https://ollama.com/api/usage?range=7d&scope=team' \## Coming soon-We plan to add custom time ranges, usage breakdowns by model and API key, and breakdowns by team member for team admins.+We plan to add custom time ranges, usage breakdowns by API key, and breakdowns by team member for team admins.## Referencediff --git a/docs/openapi.yaml b/docs/openapi.yamlindex d0b1e3394..f1f80b20d 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -1035,9 +1035,31 @@ components:output_tokens:type: integerdescription: Recorded output tokens.- UsageBucket:+ UsageGroup:+ allOf:+ - $ref: "#/components/schemas/UsageMetrics"+ - type: object+ required: [model]+ properties:+ model:+ type: string+ description: Model name.+ UsageSummary:allOf:- $ref: "#/components/schemas/UsageMetrics"+ - type: object+ properties:+ groups:+ type: array+ description: Present when group_by is requested. Currently returns up to 10 groups selected across the entire range, ranked by usage_usd or by request_count when the range includes legacy requests. Groups use the same order in every bucket; groups without requests in a bucket are omitted.+ items:+ $ref: "#/components/schemas/UsageGroup"+ remainder:+ $ref: "#/components/schemas/UsageMetrics"+ description: Combined usage from groups outside the current limit. Omitted when there are no requests from additional groups.+ UsageBucket:+ allOf:+ - $ref: "#/components/schemas/UsageSummary"- type: objectrequired: [from, until]properties:@@ -1068,6 +1090,10 @@ components:type: stringenum: [hour, day]description: "Set automatically: hour for 24h, day for 7d and 30d."+ group_by:+ type: string+ enum: [model]+ description: Selected grouping. Present when group_by is requested.from:type: stringformat: date-time@@ -1077,8 +1103,8 @@ components:format: date-timedescription: End of the range in UTC, exclusive.totals:- $ref: "#/components/schemas/UsageMetrics"- description: Usage across the entire range.+ $ref: "#/components/schemas/UsageSummary"+ description: Usage across the entire range, including groups in the remainder.buckets:type: arraydescription: Usage in chronological order, including buckets with no recorded requests.@@ -2151,6 +2177,12 @@ paths:type: stringenum: [self, team]default: self+ - name: group_by+ in: query+ description: "How to group usage within totals and buckets. Supported values: model."+ schema:+ type: string+ enum: [model]responses:"200":description: Usage for the selected range and scope.