Skip to content

Spending Controls#

Spending controls enforce AI budgets at execution time. Set limits at the organization, team, individual agent, or individual sandbox level — agents are stopped when limits are reached.

How it works#

Spending limits apply to managed agents using the LLM proxy. Before every model request:

  1. The LLM proxy checks the agent's spending against its applicable limits
  2. If the budget is exceeded, the request is rejected with a budget-exceeded notification
  3. The agent receives the notification and stops gracefully
  4. If the budget service is temporarily unavailable, the request is allowed (fail-open for availability)

Setting limits#

Limits can be set at four levels:

Level Scope Example
Organization Total AI spending across all teams and agents $5,000/month
Team Spending for a specific team's agents $1,000/month
Agent Spending for a single agent $100/month
Sandbox Spending for a single sandbox (any actor) $25/month

Limits stack — every request is checked against every applicable scope. The most restrictive limit applies.

Example: Organization limit is $5,000/month. Team limit is $1,000/month. Agent limit is $100/month. Sandbox limit is $25/month.

  • Sandbox hits $25 → that sandbox's LLM requests are rejected, other sandboxes for the same agent continue
  • Agent hits $100 → this agent is stopped, other team agents continue
  • Team hits $1,000 → all agents in this team are stopped, other teams continue
  • Organization hits $5,000 → all agents in the organization are stopped

Spending controls track LLM costs only (input tokens, output tokens, cache tokens as reported by model providers). Agent-hour platform costs and infrastructure costs are not included in spending limit calculations.

Periods#

Period Resets
Daily Every 24 hours
Weekly Every 7 days
Monthly Every calendar month

Configuration#

Spending limits can be set at any of four scopes:

  • Organization level — caps total spend across the entire organization.
  • Team level — caps spend for a specific team, within the organization's overall cap.
  • Agent level — caps spend for a single agent, within the team's cap.
  • Sandbox level — caps spend on a single sandbox. Useful for capping cost on long-running or experimental sandboxes independent of the agent that owns them; a sandbox limit applies even if the owning agent has unused agent-level budget.

Limits at more specific scopes always bind more tightly than broader ones — an agent's limit cannot exceed its team's, and a team's cannot exceed its organization's. A sandbox limit applies in addition to the limits on its owning actor.

Cost tracking#

The LLM proxy automatically extracts usage data from every model request:

  • Input tokens — tokens sent to the model
  • Output tokens — tokens generated by the model
  • Cache tokens — read and write cache hits (for prompt caching)
  • Model — which model was used
  • Provider — which provider processed the request
  • Cost — calculated cost per request
  • Attribution — the org, team, agent, and sandbox that made the request

This data feeds into the Cost Explorer for visualization and the spending limit checks for enforcement.

What happens when a limit is reached#

When an agent's spending exceeds its limit:

  1. The next LLM request is rejected with an HTTP 429 Retry-After response and an RFC 7807 budget-exceeded error body
  2. The agent is notified with a budget-exceeded message
  3. Heartbeat checks skip gracefully (not counted as errors)
  4. Scheduled tasks notify the user of the budget situation

The agent does not crash or lose state. It pauses LLM-dependent operations until the budget resets or the limit is increased.

For integration partners: the error response follows RFC 7807 Problem Details format with type budget-exceeded, including the limit period and reset time.

Cost visibility#

Monitor spending through:

  • Cost Explorer — usage summaries, time-series breakdowns, drill-down by team/agent/model
  • Agent detail page — spending for a specific agent
  • Spending limit status — agents can check their own budget via tools

Scope#

Spending controls currently apply to managed agents using the LLM proxy. Desktop AI tools and external agents use their own model providers — their LLM costs are billed directly by the provider, not through Lens Agents.

Agent-hour billing applies to all agent types. Spending controls govern the LLM costs on top of agent-hour billing.