Usage and limits
This page explains how sMind by Spacing Mind records token usage, shows plan usage windows per account, and keeps work moving when a provider reports a rate limit. It is for users watching cost and quota.
sMind by Spacing Mind, version 0.17.0. This page describes the 0.17.0 release.
smind records the tokens each run uses, shows how much of each account's plan you have used, and has a few ways to keep work moving when a provider says "rate limited".
Usage in Settings
Open Settings → Usage. The page has two blocks.
Token usage lists tokens and cost per run and per proxy request. Three rows of controls shape the table:
- Scope: Runs (the default), Proxy or All. Runs are the agent runs you started. Proxy is requests that went through smind's built-in proxy.
- Group by: Task, Provider, Model, Workspace or Space. With the Proxy scope only Model is available.
- Range: Today, 7 days or 30 days.
Each row shows a count (runs or requests), Input, Cached, Output and Reasoning tokens, and Cost. A dash means the provider did not report that number. Use Refresh to reload the table.
The cost is the figure the agent reported for the run. smind does not compute it. For a provider you signed in to with a subscription plan, the cost is only an estimate at API list prices, because a plan is not billed per token. Those rows show ≈ API price next to the amount, and the tooltip says "Estimated at API list prices; subscription plans are not billed per token". Proxy rows have no cost.
From the command line:
smind usage
smind usage --scope runs --by provider
smind usage --scope runs --by workspace --since 2026-10-01T00:00:00Z
smind usage --scope proxy --by day --until 2026-10-31T23:59:59Z| Flag | What it does |
|---|---|
--scope proxy|runs|all | Which usage to count. The default is all. |
--by <group> | One of account, model, day, workspace, task, chat, run or provider. The default is account, or task with --scope runs. |
--since <RFC3339> | Start of the range. |
--until <RFC3339> | End of the range. |
account and day group proxy traffic. workspace, task, chat, run and provider group runs. model groups both. A combination that makes no sense is rejected, for example --scope proxy --by task.
Plan windows
A subscription plan limits how much you can use in a window of time. smind reads those windows for each account and shows them in the Plan usage block at the top of Settings → Usage ("Plan windows and reset times for each account").
Each account card shows its name, provider and plan, then one bar per window:
- Session: the 5-hour window.
- Weekly: the weekly window.
- Weekly ·
<model>: a weekly window that applies to one model only, when the provider reports one.
A bar shows how much is used and when the window resets. The Percentages choice under Settings (the button in the block's header) switches between Used and Remaining. Show summary in sidebar pins a short plan usage summary to the sidebar footer. With more than one account, an Account filter picks one. Refresh all, or the refresh button on a card, fetches fresh numbers.
An account that has no plan windows, such as an API-key account, says so; that is not an error. If the login has expired, the card says to sign in again.
smind keeps the number of calls to provider usage endpoints low, so a refresh can be refused for a while.
From the command line:
smind account usage
smind account usage --refresh
smind account usage --jsonIt prints one block per account: the plan, each window with its percent used and the time to reset, and whether a window comes "from recent traffic" rather than from the provider, and marks a report as stale when it shows the last good one. --refresh asks for fresh numbers first and says when that is not allowed. --json prints the raw result.
These keys in config.yaml tune the feature. Restart the daemon after you change them.
| Key | Default | Meaning |
|---|---|---|
accountUsage.enabled | true | Turns off every outbound usage call when false. |
accountUsage.ttlSeconds | 300 | How long a reading stays fresh. 300 is also the minimum. |
accountUsage.routing | true | Lets routing steer away from exhausted accounts. |
accountUsage.exhaustThresholdPct | 100 | The percent used (1 to 100) at which an account counts as exhausted. |
accountUsage.passive | true | Learns limits from rate-limit answers on proxied requests. |
Rate limits: wait or fail over
When a provider rejects a request with a rate limit, smind notes it. The account card then shows Rate limited with the time it lasts until, and a failed run's footer in the task shows what you can do.
By hand. On the latest rate-limited run, the footer offers:
- Wait until
<time>: queues the same prompt on the same chat, to start shortly after the limit lifts (30 seconds of slack). The footer then reads "Queued · starts after<time>". A time marked with ≈ is an estimate. - Retry on
<agent>: appears when the run's agent profile names a fallback. It continues the work in a new chat on the fallback agent. - I reset my quota, retry now: appears while smind still holds a rate-limit cooldown for the provider. See "I reset my quota" below.
Automatically. An agent profile can say what to do on a rate limit. In Settings → Agents, the On rate limit field has three choices:
| Choice | Behavior |
|---|---|
| None | Do nothing. This is the default. |
| Wait | Queue the same prompt on the same chat, to run after the limit lifts. |
| Fallback | Continue on the Fallback agent you pick, in a new chat on the same task. |
On the command line, use the same names on smind profile add (and smind profile edit):
smind profile add main claude-native --on-rate-limit=wait
smind profile add alt codex-native
smind profile add steady claude-native --on-rate-limit=fallback --fallback-profile=2
smind profile ls--fallback-profile takes the id of another profile, as smind profile ls shows it. The fallback must use a different provider than the run that was limited, and that provider must not be rate-limited itself. The continuation gets a note that the earlier attempt stopped at a rate limit, the tail of its output, and the task's worktree with its changes.
Some details:
- It acts only for runs started with an agent profile, and at most once per failed run. A retry that is limited again does not trigger another action.
- Wait needs a reset time in the future. Without one, nothing is queued.
- If the provider has several accounts, smind prefers one that is not exhausted when it routes a request. It judges this from the plan windows it already has. It never fetches usage to decide, and missing or stale data does not block a request.
- Your own sends are never blocked by a rate limit. A send that comes from an agent, for example from an orchestrating task, fails at once with a message naming the provider and the time it is limited until, so the agent can pick another provider.
Why a run failed, and what to do
A failed run says why in one of a few classes, with a next step. The task footer, the inbox, smind task runs, smind task wait and the MCP tools all show the same class and step.
| Class | Meaning | Next step |
|---|---|---|
auth_expired | The provider refused the login. | Sign in again to that account in Settings → Providers. Never retried and never failed over: it cannot work until you sign in. |
plan_window_exhausted | The plan's usage window (5 hours, weekly) is used up. | Wait until it resets, or continue on the profile's fallback agent. |
model_not_in_plan | The account's plan does not include the model you chose. | Pick another model. Never retried on the same account. |
transient_429 | A short throttle from the provider, not a quota. | A run from an agent profile or an orchestrating task is retried twice by itself (after 30 seconds, then 2 minutes; the provider's own wait hint wins, between 5 seconds and 5 minutes). A plain send of yours gets a Retry step instead. No retry starts while the provider is on cooldown. |
rate_limited | A limit smind cannot tell apart (no window, no reset time). | Retry after a short wait. |
cli_exited | The agent program ended without a result. | Continue the run. |
A failed run also appears in the inbox as a Run failed item, with its next step as a button, until a later run replaces it; auth_expired and model_not_in_plan are marked high attention because only you can fix them. On the command line, smind task wait exits 6 for the limit classes and 7 when you must fix setup (see task wait).
The provider and model picker shows the same states before you send. See Why a provider or model is greyed out.
I reset my quota
smind keeps a provider on cooldown until the reset time the provider gave, even if you reset or top up the quota yourself in the meantime. To tell smind the limit is gone, use I reset my quota, retry now, on a rate-limited run's footer or in Settings → Providers (the provider shows "Rate limited until <time>"). On the command line:
smind cooldown ls
smind cooldown clear glmClearing the cooldown lets agent sends to that provider start again, and wakes the retries that Wait queued for it: they start now instead of at the old reset time. Each retry starts once; clearing again does nothing. Only a person can do this: agents cannot clear a cooldown, and the action is not available to plugins or automations. Clearing does not check the provider: if the limit is still in force, the retried run fails and a new cooldown starts.