97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
---
|
||
name: usage
|
||
description: >
|
||
How much of the Ollama Cloud plan has been spent — session and weekly usage,
|
||
per-model request counts, and delta reports over the continuously sampled
|
||
history. Triggers on: "ollama usage", "ollama quota", "ollama credits",
|
||
"ollama limits", "how much of the ollama plan is left", "ollama usage report".
|
||
---
|
||
|
||
# Usage
|
||
|
||
Shows Ollama Cloud credit usage for the current API key.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
uv run skills/usage/scripts/ollama_usage.py
|
||
```
|
||
|
||
The key comes from `OLLAMA_API_KEY` — the environment first, then the
|
||
`workspace/.env` file (created by the user). If it is missing or fails
|
||
(401/403), tell the user — never scrape the website.
|
||
|
||
## Output
|
||
|
||
Present the script's lines as-is — same lines, same order; translate the labels
|
||
into the user's language, keep the numbers exact.
|
||
|
||
```text
|
||
Ollama Cloud usage
|
||
Session: <pct> %, resets HH:MM TZ (in H h M min)
|
||
Weekly: <pct> %, resets in <countdown>
|
||
Models (request count, weekly window):
|
||
<model>: <count>
|
||
```
|
||
|
||
Per-model numbers belong only under "Models", never inline on the Session or
|
||
Weekly line.
|
||
|
||
The Session line has two other shapes, both correct output and not a failure:
|
||
the percentage alone (the history holds no rollover to anchor the window), and
|
||
`window expired — the next one starts with the next request`.
|
||
|
||
Times are printed in the server's local zone, taken from the system — no zone
|
||
is hardcoded.
|
||
|
||
## Reset times
|
||
|
||
`/api/usage` carries **no reset timestamps**, neither in the body nor in the
|
||
response headers (re-checked 2026-09-15). Both countdowns are derived.
|
||
|
||
- **Weekly:** next Monday 00:00 UTC, `until_next_monday()`. Matches the dashboard.
|
||
- **Session:** a 5-hour window anchored by the **first request after the previous
|
||
one ran out**, not a fixed grid. So `session_window_end()` takes the newest
|
||
rollover in `samples` and adds 5 h, and nothing is extrapolated past it — once
|
||
the window runs out there is no next time until a request opens one.
|
||
|
||
**The reset is never guessed.** With no rollover in the history the Session line
|
||
carries the percentage alone; a confident wrong number is worse than none.
|
||
|
||
Do not calibrate our countdown against the dashboard's: it rounds an unknown way
|
||
(it showed "4 hours" and "3 hours" seven minutes apart), which is why the output
|
||
prints the wall-clock time too.
|
||
|
||
## Continuous sampling
|
||
|
||
A cron job runs `scripts/ollama_usage_poll.py` every minute and appends to
|
||
`db/ollama_usage.sqlite` (table `samples`) whenever anything changed. Table
|
||
`meta` holds a single row — timestamp and status of the last poll — so a report
|
||
that has not moved can be told apart from a dead poller.
|
||
|
||
For a delta report over that data:
|
||
|
||
```bash
|
||
uv run skills/usage/scripts/ollama_usage_report.py [--since ISO] [--until ISO]
|
||
```
|
||
|
||
Default window is the last 24 hours. Per-model **request counts** are the exact
|
||
figure there — `limits.*.usage` has a resolution of 0.1 %, so short-interval
|
||
percentage deltas are noise.
|
||
|
||
The report closes with a `Session window:` line and `Last poll:`. From the second
|
||
recorded rollover on it also prints `Rollover gap:` lines, which test the window
|
||
model: a gap longer than 5 h confirms request-anchoring, one exactly equal to it
|
||
across a long idle stretch would point back to a fixed grid.
|
||
|
||
## Notes
|
||
|
||
- Endpoint: `GET https://ollama.com/api/usage`, header
|
||
`Authorization: Bearer <key>` (verified 2026-09; issue #15132 is stale).
|
||
- `limits.*.usage` is a fraction of the plan limit (× 100 = % as on the
|
||
dashboard).
|
||
- `activity.cost` returns $0.00000 on the Pro plan — broken, omitted from
|
||
the output.
|
||
- The `~/.ollama/id_ed25519` key does not work — only an API key minted at
|
||
ollama.com/settings/keys.
|