Skip to content

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.mdx
index 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.
## Reference
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index d0b1e3394..f1f80b20d 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1035,9 +1035,31 @@ components:
output_tokens:
type: integer
description: 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: object
required: [from, until]
properties:
@@ -1068,6 +1090,10 @@ components:
type: string
enum: [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: string
format: date-time
@@ -1077,8 +1103,8 @@ components:
format: date-time
description: 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: array
description: Usage in chronological order, including buckets with no recorded requests.
@@ -2151,6 +2177,12 @@ paths:
type: string
enum: [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.