Budgets and limits

Budgets#

A budget caps or watches what the organisation, one project or one gateway key spends in a calendar month (UTC). Owners and admins set budgets in the Budgets section of the organisation's Usage page, or with the CLI. Members see budgets without amounts.

kuiper budgets create --scope org --limit 200                    # block at $200
kuiper budgets create --scope project -p proxima --limit 20 \
  --action notify --notify-at 50,90                              # alerts only
kuiper budgets create --scope key --key gk_… --limit 5
kuiper budgets                                                   # spent, limit, alerts
kuiper budgets set bud_… --limit 40
kuiper budgets rm bud_…

What counts#

• The organisation or a project: everything it is billed for this month, the same total as the Usage page, plus what its live browser sessions and sandboxes hold.
• A key: the browser sessions, quick actions, proxy traffic and sandboxes made with it.

How a budget blocks#

• Holds. A new or resumed browser session or sandbox holds its first hour, or its whole timeout if that is shorter, at its price. A quick browser action holds its own price. A block budget refuses whatever wouldn't fit with 402 budget_exceeded. The hold itself is never charged: you pay for the time a session or sandbox actually ran.
• Long sessions hold one hour at a time. At the end of each hour, a session or sandbox whose block budget can't pay for the next hour is released with releaseReason: "budget_exceeded".
• Extending a sandbox's timeout holds what the extension adds to its current hour.
• Kuiper's gateways learn what has been spent every few seconds. When several gateways serve you at once, a budget can be overshot by what they admit in those seconds.

Alerts#

Each percentage in --notify-at is recorded once a month, in the activity log and as a banner across the dashboard. A notify budget does nothing else.

When a budget is deleted, its spend history stays. A budget on a project or key is deleted with that project or key.

Limits#

Limits protect everyone from runaway agents. They apply whatever your budgets say.

• Hibernated sessions and sandboxes don't count towards the concurrent limits.
• Request limits don't count CDP and live-view traffic, or traffic to a sandbox's exposed ports.
• Every 429 carries Retry-After, in seconds.
• If you need higher limits, ask Kuiper.

Kuiper can also stop an organisation's browsers or sandboxes, for example after abuse. Creating or resuming one then answers 403 browsers_stopped or sandboxes_stopped, and live ones end with releaseReason: "stopped_by_admin".

Reading a refusal#

Every refusal has a code, so a client can tell a budget from a limit: