Cost Control

How the credit system works, how to set budgets at every level, what counts as a credit, how to monitor spending in real time, and practical strategies for reducing costs without reducing output.

The credit system#

Capx uses credits as the universal unit of compute. One credit is approximately $0.01 of underlying cost. Every billable action your agents take, including LLM inference, tool execution, and storage, is metered in credits. This abstraction lets you set budgets and compare costs across different models and providers without converting between token counts and pricing tiers.

Credits are deducted in real time as actions execute.

What costs credits

Cost reference table#

The following table shows typical credit costs for common actions. Actual costs depend on prompt length, output length, and the model used.

Per-agent budgets#

Every agent has its own credit budget, defined in the budget block of its configuration in company.yaml. Per-agent budgets let you allocate more resources to high-value agents (like your strategist) and constrain low-priority ones.

agents:
  strategist:
    role: strategist
    adapter:
      provider: claude
      model: claude-sonnet-4
    budget:
      daily: 1500              # Max 1,500 credits per day
      monthly: 30000           # Max 30,000 credits per month
      per_task: 300            # Max 300 credits for a single task
      alert_threshold: 0.8     # Alert founder at 80% usage

Per-company budgets#

Company-level budgets are an outer boundary. Even if every agent has budget remaining, the company budget can pause all activity. This prevents a scenario where five agents each spend their full daily allocation and the total exceeds what you intended.

governance:
  spend_caps:
    daily: 5000                # Max 5,000 credits/day total
    monthly: 80000             # Max 80,000 credits/month total
    per_action: 500            # No single action can exceed 500 credits
    alert_thresholds:
      - at: 0.5
        notify: dashboard
      - at: 0.8
        notify: [dashboard, email]
      - at: 0.95
        notify: [dashboard, email, sms]

Cost monitoring#

Capx provides multiple ways to monitor costs:

• CLI: the fastest way to check current spending from a terminal.
• REST API: query cost data programmatically.
• Casa dashboard: monitor spending from the browser.

CLI cost commands

capx costs --company my-company

# AGENT        TODAY     THIS WEEK   THIS MONTH   BUDGET    REMAINING
# strategist   142cr     1,018cr     4,240cr      30,000    25,760
# engineer     280cr     1,890cr     8,720cr      20,000    11,280
# marketer     38cr      285cr       1,150cr      15,000    13,850
# support      64cr      448cr       1,680cr      8,000     6,320
# TOTAL        524cr     3,641cr     15,790cr     80,000    64,210

API cost endpoints

# Current month summary
curl https://api.capx.ai/v1/companies/my-company/costs \
  -H "Authorization: Bearer capx_sk_live_..."

Cost optimization#

The most effective way to reduce costs is to match model capability to task complexity. Here are the strategies that make the biggest difference, ranked by impact.

# Expensive: 96 heartbeats/day at ~5 credits each = 480 credits/day idle
heartbeat:
  cron: "*/15 * * * *"

# Moderate: 24 heartbeats/day at ~5 credits each = 120 credits/day idle
heartbeat:
  cron: "0 * * * *"

# Efficient: 3 heartbeats/day at ~5 credits each = 15 credits/day idle
heartbeat:
  cron: "0 9,13,17 * * 1-5"

steps:
  - id: classify
    agent: marketer
    adapter:
      provider: claude
      model: claude-haiku-4      # Cheap model for classification
    tool: classify_messages
    with:
      source: inbox

  - id: draft
    agent: marketer
    # Uses default adapter (claude-sonnet-4), a better model for writing
    tool: generate_copy
    with:
      type: email_reply

Alerts and notifications#

Capx sends alerts when spending approaches or exceeds your configured thresholds. Alerts are delivered through the channels you specify: the Casa dashboard, email, SMS, or webhooks.

governance:
  alerts:
    webhook:
      url: "https://your-api.com/webhooks/capx-costs"
      events:
        - budget.warning
        - budget.exceeded
        - cost.spike
      headers:
        X-Webhook-Secret: "${{ secrets.WEBHOOK_SECRET }}"

    email:
      recipients:
        - founder@example.com
      events:
        - budget.exceeded
        - cost.spike

    sms:
      recipients:
        - "+1234567890"
      events:
        - budget.exceeded

CLI cost command reference#

Plan credit allowances#

Each Capx Casa plan includes a monthly credit allowance. Additional credits can be purchased in packs.

Next steps#