> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apollospace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spending Caps

> How to set hard usage limits per organization, per agent, or per user — before your balance runs out.

## Why caps exist

AI agents have an uncomfortable talent: **spending very fast**.
An ambiguous prompt, an unexpected loop, an integration that keeps returning
errors while the agent retries — any of these scenarios can burn through
Stars in minutes.

Caps are **hard limits** you configure **before** any spending happens,
ensuring that even in the worst case your usage stays under control.

## The four protection layers

Apollo Space applies caps in layers. Before each billable call, the
system checks:

<CardGroup cols={2}>
  <Card title="1. Wallet balance" icon="wallet">
    The fundamental safeguard — if the wallet is empty, no new
    calls are authorized. You can operate freely as long as the
    balance is positive.
  </Card>

  <Card title="2. Monthly cap per organization" icon="building">
    Even with a positive balance, you can set **a monthly spending
    limit for the entire org**. Once reached, all paid calls stop
    until the next cycle (or until you raise the cap).
  </Card>

  <Card title="3. Daily cap per agent" icon="robot">
    Limits how much **each agent** can spend **per day**. Useful for
    preventing a single looping agent from consuming the entire
    day's budget.
  </Card>

  <Card title="4. Monthly cap per user × agent" icon="user-tag">
    The most granular combination — how much **user X using
    agent Y** can spend in a month. Useful on larger teams where
    you want to allocate budget per person.
  </Card>
</CardGroup>

## How to configure

Everything lives in **Settings → Spending Caps** inside the app.

### Org cap

Configured **once** by the org owner/admin. Typically revisited every
few months as actual usage evolves.

### Agent cap

Configured **per agent** when creating or editing a persona. Sensible
defaults are applied automatically (you don't need to start from
scratch); customize only when the default doesn't fit.

### User × agent cap

Configured **optionally** by the admin. You don't need to fill it in
for every pair — only for specific users you want to limit explicitly
(e.g., an intern who needs a boundary, a premium agent that only
authorized people should use).

## Precedence

All 4 layers are checked **in order**. The first protection that fires
blocks the call — the rest are not even evaluated.

Example: if the balance is empty, **it doesn't matter** whether the org
cap still has headroom or the user still has quota — the call is
blocked at layer 1.

This means you **don't need to configure all 4 layers**.
Layer 1 (balance) already protects you from the worst case; the others
are fine-tuning tools for specific scenarios.

## What the user sees when a cap fires

When a call is blocked by a cap, the agent:

* Stops execution immediately (no retry)
* Surfaces a **clear message** in the chat indicating **which cap was
  reached** (e.g., "This agent's daily limit has been reached — you can
  raise it in Settings → Caps")
* Suggests the corrective action (raise the cap, wait for the next cycle,
  switch to another agent)

No paid call ever happens "silently" — users always know when they've
hit a limit.

## Audit

Every time a cap fires, it is recorded in the org's event history with:

* Which cap triggered (balance / org / agent / user×agent)
* What the configured value was
* How much the call would have cost
* Who triggered it (which user + which agent)
* Timestamp

Useful for spotting patterns — if a cap is firing frequently, the
configuration may need adjustment.

## Recommended strategy

For teams just getting started:

<Steps>
  <Step title="Trust the balance + initial bonus">
    Don't configure anything yet. The initial bonus is generous
    enough for comfortable exploration.
  </Step>

  <Step title="Once you go into real operations, add agent caps">
    Set a daily limit for your most-used agents (Marcus, Athena).
    A reasonable default — you can adjust later as actual usage
    becomes clear.
  </Step>

  <Step title="Once you pass 5 active users, add an org cap">
    A monthly limit for the entire org prevents surprises at the
    end of the month. Calculate it based on 70–80% of your plan's
    monthly credit.
  </Step>

  <Step title="User × agent caps only for specific cases">
    Don't default this for everyone. Use it only when governance
    requires it (e.g., an intern, a premium agent).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Stars — overview" icon="star" href="/en/billing/stars">
    How the wallet that caps protect actually works.
  </Card>

  <Card title="Plans and packs" icon="box" href="/en/billing/plans-and-packs">
    How to size your balance and buy additional credits.
  </Card>

  <Card title="Agents" icon="robot" href="/en/concepts/agents">
    Every agent respects caps automatically — no additional
    code required.
  </Card>
</CardGroup>