> ## Documentation Index
> Fetch the complete documentation index at: https://agent37.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing
> Prepaid and managed in the dashboard: one workspace wallet funds compute and managed usage.
Billing is prepaid. You top up one workspace wallet in the dashboard, and everything draws from it: instance compute and managed usage.
## How the balance works
* **\$1 free to start.** Your first visit to the dashboard grants a one-time \$1 credit, enough to run your first instance for days, or a mostly-idle [auto-sleep](/agents-api/instances#auto-sleep) instance for a month or more. Until your first real top-up, the workspace runs one instance of any template, up to the 2 vCPU / 4 GB shape; a larger shape returns `403 tier_limit`. Your first top-up unlocks the 4/8 and 8/16 shapes, and up to 10 instances; once your top-ups total \$500 the cap rises to 50. See [Instance limits](#instance-limits).
* **Top up in the dashboard.** Add funds at [dashboard/cloud/billing](https://www.agent37.com/dashboard/cloud/billing). Top-ups are \$5 to \$1000 each, paid through Stripe.
* **Automatic top-up is on by default.** Your first top-up saves its card and turns on a refill rule (below \$10, buy \$25) so the wallet refills itself; adjust or turn it off any time. See [Automatic top-up](#automatic-top-up).
* **Instances draw it down.** Compute is metered per minute: time an instance spends running bills its full rate, time spent stopped or sleeping bills its disk alone. See [Per-minute metering](#per-minute-metering).
* **Managed usage draws it down.** Managed LLM, Brave search, and Composio calls are metered at cost against the same wallet, gated by each instance's [budget](/agents-api/budgets).
* **Delete to stop billing.** Deleting an instance settles its final minutes and ends billing. Nothing is ever prepaid, so there is nothing to refund.
There are no balance or billing endpoints on `/v1`. The wallet, top-ups, and the ledger are managed entirely in the [dashboard](https://www.agent37.com/dashboard/cloud/billing).
## Instance limits
How many instances a workspace can run at once depends only on how much it has topped up:
| Workspace | Instances |
| ------------------------------------ | -------------------------------- |
| Free (before your first top-up) | 1, up to the 2 vCPU / 4 GB shape |
| Topped up at least once (any amount) | 10, all shapes |
| Top-ups total \$500 or more | 50, all shapes |
The cap rises on its own: your first top-up lifts the workspace to 10 instances, and once your top-ups total \$500 it becomes 50 — nothing to request or configure. Need more than 50? Email [vishnu@agent37.com](mailto:vishnu@agent37.com) or use the chat bubble in the dashboard.
These are caps on how many instances you can run at once, not a balance requirement: each instance simply [meters its own compute](#per-minute-metering) from the wallet, with no extra reserve for holding several.
## Compute pricing
Compute is priced from the instance's `resources`:
| Resource | Rate |
| -------- | ------------------------- |
| vCPU | \$0.80 per vCPU per month |
| RAM | \$0.70 per GB per month |
| Disk | \$0.09 per GB per month |
Applied to the shapes at their default disk:
| Shape | Price at the default disk |
| ----------------------------------------------------------------- | ------------------------- |
| 1 vCPU / 3 GB RAM / 6-20 GB disk (`agent37-hermes-small` only) | \$3.44 |
| 2 vCPU / 4 GB RAM / 6-20 GB disk (default for standard templates) | \$4.94 |
| 4 vCPU / 8 GB RAM / 20-40 GB disk | \$10.60 |
| 8 vCPU / 16 GB RAM / 40-80 GB disk | \$21.20 |
Disk is any whole number of GB within the shape's range and defaults to the range minimum; disk above the minimum adds \$0.09 per GB per month. See [Instances](/agents-api/instances) for how to pick a shape with `resources` on create.
An instance with [auto-sleep](/agents-api/instances#auto-sleep) on bills its awake minutes at **4x these compute rates**: the platform keeps its capacity wakeable on demand instead of sharing it. Time spent asleep bills disk alone, so a mostly-idle auto-sleep instance still comes out well below the always-on price. See [Per-minute metering](#per-minute-metering).
## Per-minute metering
The monthly price is the rate; the wallet is metered per minute (the monthly price divided by 730 hours, divided by 60). What a minute costs depends on what the instance holds:
| Time spent | Meters at |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `running`, and the transitional states (`starting`, `restarting`, `updating`, `stopping`) | The full compute rate. With [auto-sleep](/agents-api/instances#auto-sleep) on, 4x the compute rate. |
| `sleeping` or `stopped` | The disk rate alone: \$0.09 per reserved GB per month. |
| Parked in cold storage (long-idle sleepers moved off their host) | \$0.03 per GB per month, on the actual compressed bytes stored. |
**Create checks a day, debits nothing.** `POST /v1/instances` requires the wallet to hold one day of the instance's running rate (for an `auto_sleep: true` create, one day at its 4x rate); below that, the create returns `402 insufficient_balance` and nothing is provisioned. Nothing is debited at create: the meter starts when the instance first reaches `running`, so a failed create costs nothing and there is nothing to refund.
```json theme={null}
{
"error": {
"code": "insufficient_balance",
"message": "This instance costs $0.0068 per hour, metered per minute; creating it requires at least one day of balance ($0.1624). Add balance to your workspace and try again."
}
}
```
**Each instance meters on its own.** Every instance draws its own metered debits from the wallet; there is no extra balance reserve for running several at once. How many you can run at once is set by your [instance limit](#instance-limits), not by your balance.
**Sleep and stop cut the rate; delete ends it.** An instance bills for as long as it exists, but only for what it holds. Stopping (or [auto-sleep](/agents-api/instances#auto-sleep)) releases CPU and RAM and keeps the disk, so parked time bills disk alone. An auto-sleep instance pays for its wake guarantee in its awake minutes, which bill at 4x the compute rate, but one that spends most of its life asleep still costs mostly its disk, about \$0.54 per month at 6 GB. Deleting an instance settles the final window and billing stops.
**The meter settles behind the scenes.** Whole minutes are billed at every lifecycle transition and at least hourly; you never see a per-minute charge on an API call. Each debit lands in the [ledger](#ledger-and-spend-visibility) as a metered compute entry.
## Automatic top-up
Automatic top-up keeps instances from being suspended when the balance runs low: when it falls below your threshold, your card is charged for a fixed amount. The rule is checked every hour, and once more right before any instance would be suspended, so instances stay up as long as the card charges.
* It turns on by default at your first top-up (below \$10, buy \$25), charging the most recently saved card. Adjust both amounts or turn it off at [dashboard/cloud/billing](https://www.agent37.com/dashboard/cloud/billing).
* The threshold can be \$1 to \$1000. The purchase amount follows the usual \$5 to \$1000 top-up range.
* If a charge fails, automatic top-up turns itself off and emails the workspace owner. Add funds manually, which saves a new card, then re-enable it.
## Past due and suspension
The meter is post-paid within the hour, so a busy instance can carry the balance below zero before the hourly settle catches it. When a settle leaves the wallet negative, and [automatic top-up](#automatic-top-up) is off or could not charge, the workspace's instances are suspended: running ones are force-slept, every one is flagged `past_due: true`, and the workspace owner is emailed. A request to a suspended instance's URL returns `402` with `{"error": "instance_suspended"}` instead of waking it, and suspended time is never billed.
`true` while the instance is suspended for non-payment. Cleared by topping up.
```json theme={null}
{
"id": "ab12cd34ef",
"status": "sleeping",
"past_due": true
}
```
Topping up reactivates immediately: the flag clears, the meter re-anchors at the top-up (the suspended gap is never back-billed), and the next request to each instance's URL wakes it. A suspension discards no data, but the force-sleep takes no checkpoint, so the first wake after one boots fresh, like `start` after `stop`.
Branch on the error `code`, not the message. See [Errors](/agents-api/errors) for the full list and the response shape.
## Managed usage
Managed LLM, Brave search, and Composio calls debit the same wallet at cost, but only within each instance's budget: a monthly cap that resets each UTC month plus optional one-time top-up headroom. The default cap is \$0, so an instance spends nothing on managed services until you raise its cap or top it up. When a managed call is refused, the 402 reason tells you which pot ran dry: `insufficient_balance` means the wallet is empty, `instance_budget_exhausted` means the wallet has funds but the instance hit its cap. See [Budgets](/agents-api/budgets) for the endpoints, rates, and both 402 reasons.
## Ledger and spend visibility
Every wallet movement is recorded: top-ups, the signup credit, and metered compute debits land in an append-only ledger, while managed usage is metered per call into its own usage ledger and shown as a per-instance spend breakdown. Review the ledger, your balance, and the spend breakdown at [dashboard/cloud/billing](https://www.agent37.com/dashboard/cloud/billing). For managed spend on a single instance, `GET /v1/instances/{id}/usage` returns a monthly rollup; compute charges are dashboard-only and never appear there.