Spending Controls

LLM API calls cost money. Cortask includes spending controls that let you set hard limits on token consumption and estimated cost over a rolling period.

Why Spending Controls Matter

Without limits, a long-running agent loop, a cron job running more often than expected, or channel conversations from multiple users can accumulate significant costs. Spending controls act as a safety net that stops all agent runs once the threshold is reached.

Configuration

Configure spending limits in ~/.cortask/config.yaml:

spending:
  enabled: true
  maxTokens: 5000000       # optional: total token limit for the period
  maxCostUsd: 10.00        # optional: estimated cost limit in USD
  period: monthly           # daily, weekly, or monthly

You can also update these settings through the REST API:

PUT /api/config

{
  "spending": {
    "enabled": true,
    "maxTokens": 5000000,
    "maxCostUsd": 10.0,
    "period": "monthly"
  }
}

Options

Field	Type	Description
enabled	boolean	Whether spending limits are active. Default: false.
maxTokens	number	Maximum total tokens (input + output) for the period. Optional.
maxCostUsd	number	Maximum estimated cost in USD for the period. Optional.
period	string	"daily", "weekly", or "monthly". Default: "monthly".

You can set either maxTokens, maxCostUsd, or both. If both are set, whichever limit is reached first will block further runs.

Period Boundaries

• Daily -- resets at midnight (server local time)
• Weekly -- resets at midnight on Sunday
• Monthly -- resets at midnight on the 1st of each month

How Limits Are Enforced

Spending limits are checked at three points:

1. WebSocket chat -- before starting an agent run from the web UI. If the limit is reached, an error message is sent back to the client instead of starting the run.
2. Cron jobs -- before executing a scheduled job. If the limit is reached, the job throws an error and does not run.
3. Channel messages -- before processing a message from Telegram, Discord, or WhatsApp. If the limit is reached, a short error message is returned to the channel.

Cost estimation uses per-model pricing data. Cortask maintains a table of known model prices (input and output cost per million tokens) and falls back to hardcoded definitions for common models. If pricing data is not available for a model, the cost is recorded as $0 but tokens are still counted.

Usage Tracking and History

Every agent run records its token usage in a SQLite database. You can review usage through the API:

Current period summary:

GET /api/usage

Returns total input tokens, output tokens, combined tokens, estimated cost, and record count for the current spending period.

Daily history:

GET /api/usage/history?days=30

Returns per-day totals for the specified number of days, useful for charting usage trends.

The web UI displays usage information in the settings panel, showing how close you are to your configured limits.