Token Budgets

Ithil’s budget engine enforces daily token limits per agent, preventing runaway AI costs and allowing you to predictably control spend.

What counts as a token

Every tool call response is counted. The budget engine uses a token counter on the raw response body returned by your downstream API. The count is added to the agent’s daily running total in Redis before the response is forwarded to the agent.

If a tool call would push the agent over its limit, the gateway returns 429 and the response is not forwarded — the downstream call still occurred, but the agent receives an error instead of the result.

Default limit

Set by Ithil:Budget:DefaultDailyTokenLimit (default: 100000). This limit applies to any agent that does not have an explicit per-agent limit configured.

{
  "Ithil": {
    "Budget": {
      "DefaultDailyTokenLimit": 100000
    }
  }
}

Per-agent limits

Per-agent limits are configured through:

• Ithil Dashboard → Agents tab → select agent → set token limit
• Management API — PUT /management/agents/{agentId}/budget

Per-agent limits take precedence over the default.

What happens at the limit

When an agent reaches its daily limit, the gateway:

1. Returns 429 Too Many Requests to the caller
2. Returns a JSON-RPC error to the agent:

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32029,
    "message": "Daily token budget exhausted. Limit resets at midnight UTC."
  }
}

The downstream API is not called — no additional cost is incurred for the blocked request.

Reset schedule

All daily token budgets reset at midnight UTC. The reset is applied automatically by the gateway — no manual action required.

Dashboard view

Budget consumption per agent is visible in the Ithil Dashboard under the Budget tab:

• Current usage vs. daily limit
• Usage trend over time
• Remaining budget as a percentage
• Historical reset logs