mirror of
https://github.com/ollama/ollama.git
synced 2026-11-10 15:02:13 -06:00
2476d5ead1
* docs: add model grouping to cloud usage Document group_by=model in the cloud usage guide and OpenAPI schema. Explain group selection and remainder, and show responses with multiple models across time buckets. * Update docs/api/cloud-usage.mdx Co-authored-by: Bruce MacDonald <brucewmacdonald@gmail.com> --------- Co-authored-by: Bruce MacDonald <brucewmacdonald@gmail.com>
270 lines
7.3 KiB
Plaintext
270 lines
7.3 KiB
Plaintext
---
|
||
title: Cloud usage
|
||
sidebarTitle: /api/usage
|
||
openapi: /openapi.yaml GET /api/usage
|
||
---
|
||
|
||
<RequestExample>
|
||
|
||
```shell Request
|
||
curl 'https://ollama.com/api/usage?range=24h' \
|
||
-H "Authorization: Bearer $OLLAMA_API_KEY"
|
||
```
|
||
|
||
</RequestExample>
|
||
|
||
<ResponseExample>
|
||
|
||
```json Response (22 empty buckets omitted)
|
||
{
|
||
"range": "24h",
|
||
"scope": "self",
|
||
"granularity": "hour",
|
||
"from": "2026-09-30T02:00:00Z",
|
||
"until": "2026-10-01T02:30:00Z",
|
||
"totals": {
|
||
"request_count": 15,
|
||
"usage_usd": 0.01718,
|
||
"input_tokens": 106000,
|
||
"cached_input_tokens": 46000,
|
||
"output_tokens": 13600
|
||
},
|
||
"buckets": [
|
||
{
|
||
"from": "2026-09-30T12:00:00Z",
|
||
"until": "2026-09-30T13:00:00Z",
|
||
"request_count": 4,
|
||
"usage_usd": 0.0052,
|
||
"input_tokens": 24000,
|
||
"cached_input_tokens": 0,
|
||
"output_tokens": 3200
|
||
},
|
||
{
|
||
"from": "2026-10-01T00:00:00Z",
|
||
"until": "2026-10-01T01:00:00Z",
|
||
"request_count": 8,
|
||
"usage_usd": 0.0088,
|
||
"input_tokens": 64000,
|
||
"cached_input_tokens": 40000,
|
||
"output_tokens": 8000
|
||
},
|
||
{
|
||
"from": "2026-10-01T02:00:00Z",
|
||
"until": "2026-10-01T02:30:00Z",
|
||
"partial": true,
|
||
"request_count": 3,
|
||
"usage_usd": 0.00318,
|
||
"input_tokens": 18000,
|
||
"cached_input_tokens": 6000,
|
||
"output_tokens": 2400
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
</ResponseExample>
|
||
|
||
New usage may take time to appear.
|
||
|
||
For your remaining included and purchased credits, use [Balance](/api/balance).
|
||
|
||
Unsupported or repeated query parameters return `400`. Errors follow Ollama's [JSON error format](/api/errors#error-messages).
|
||
|
||
## Time ranges
|
||
|
||
| Range | Starts at | Bucket size | Buckets |
|
||
| ----- | ------------------------------------------------- | ----------- | ------- |
|
||
| `24h` | 24 hours before the start of the current UTC hour | Hour | 25 |
|
||
| `7d` | Seven days ago at 00:00 UTC | Day | 8 |
|
||
| `30d` | Thirty days ago at 00:00 UTC | Day | 31 |
|
||
|
||
Every range ends at the time of the request. For example, at 02:30 UTC on October 1, `24h` starts at 02:00 UTC on September 30. It returns 24 complete hourly buckets followed by the current 02:00–02:30 bucket. The `7d` and `30d` ranges return seven and thirty complete days, followed by today so far.
|
||
|
||
Buckets appear in chronological order, including zeroes for hours or days with no recorded requests. The final bucket covers the current hour or day and has `partial: true`.
|
||
|
||
All timestamps are in UTC. Each `from` is inclusive and each `until` is exclusive.
|
||
|
||
## Usage totals and buckets
|
||
|
||
`totals` summarizes usage across the entire range. `buckets` breaks that usage into hours or days.
|
||
|
||
`granularity` is set automatically: `hour` for `24h` and `day` for `7d` and `30d`. The top-level `from` and `until` describe the entire range; each bucket has its own boundaries.
|
||
|
||
`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 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>
|
||
|
||
## Rate limits
|
||
|
||
This endpoint allows 10 requests per minute per user, shared across API keys and devices. We recommend polling once per minute. A `429` response includes a `Retry-After` header with the number of seconds to wait before retrying.
|
||
|
||
## Team usage
|
||
|
||
By default, everyone sees their own usage (`scope=self`).
|
||
|
||
Team admins can use `scope=team` to see usage for the whole team:
|
||
|
||
```shell
|
||
curl 'https://ollama.com/api/usage?range=7d&scope=team' \
|
||
-H "Authorization: Bearer $OLLAMA_API_KEY"
|
||
```
|
||
|
||
## Coming soon
|
||
|
||
We plan to add custom time ranges, usage breakdowns by API key, and breakdowns by team member for team admins.
|
||
|
||
## Reference
|