# Billing

Plans, top-ups and their bonus, and the calls that read and buy them.

Every account starts on the free plan: no monthly fee, and what it uses is paid from top-ups. A paid plan is a monthly price that is spent on what you use: the $100 plan pays for $100 of it. Sandboxes are billed by the second at the list price of their size, and mail by the message, from what the plan includes and then from top-ups, at the same rates on every plan.

| Plan, a month | Credits included | Running at once | Free burst | Sizes |
| --- | --- | --- | --- | --- |
| Free | $0 | 20 | 20 | tiny and small |
| $100 | $100 | 100 | 100 | tiny, small and medium |
| $500 | $500 | 600 | 200 | every size |
| $2,000 | $2,000 | 2,000 | 400 | every size |

Both counts are in small sandboxes: a tiny counts half, a medium 2, a large 4. A start past the running count is refused. The free burst is how many start at once for nothing; starting faster costs a burst fee, about $0.04 for each small sandbox past it at twice the free burst, which comes out of the plan's credits, up to a monthly budget. See [bursts](https://agental.io/docs/usage#bursts).

- A new sandbox, a fork and a template's start are held to the sizes of the plan. A larger one is refused with `402 size_not_on_plan`, and the message names the plan that makes it.
- A sandbox made before you move to a smaller plan keeps its size: it still starts, and is billed at the same rates.

## Starting out

- Every account starts on the free plan, and saves a card before it runs anything. A plan's button on the Pricing page takes you through sign-up, by email, GitHub or Google, straight to saving a card, or to that plan's checkout.
- Signed up another way, or left the checkout first? The console shows the choice before any other page, each time it opens, until a card is saved or a plan has started. Settings stays open, to close the account instead.
- Back from the checkout, the console opens on your sandboxes as soon as Stripe tells us, usually within seconds. `needsPlan` in `GET /v1/billing` is true while the account must still save a card or start a plan.
- Until then, no new API key is made and no terminal is signed in: both are refused with `402 billing_required`, whose message gives the console's address. Signing the terminal in offers to save a card, or a plan, on the same page first. `npx agental@latest sh` with a key already offers to open it in your browser, and goes on once it is done.

## The free plan

- No monthly fee. It makes tiny and small sandboxes; a medium needs the $100 plan, and a large the $500 plan.
- Save a card to use it: Stripe checks it and charges nothing. Once it is saved the account gets $10 of credit, once an account and once a card. It does not expire.
- What it runs is paid from that credit and from top-ups, at the same list prices as every plan. Turn on auto-reload so it never runs dry.
- Until the account has paid for something, a top-up of any size, it runs and starts at most 2 small sandboxes at once (a tiny counts half). From the first top-up, 20. A start past the count is refused with `429 running_limit_reached`.
- Starting faster than the free burst costs burst fees, as on any plan.
- To go back to the free plan from a paid one, cancel the plan in the billing portal, from Billing in the console.

## Top-ups

- A top-up is credits bought once: any whole number of dollars from $15 to $100,000. From $200 on it adds a bonus.
- The plan's credits are spent first, then the top-ups. What is left of the plan's credits when a month ends is gone. What is left of the top-ups carries over: they do not expire.
- When both run out, running sandboxes are stopped within a minute, with their disks kept, and the account is emailed. A new sandbox, or a start, is refused with `402 out_of_credit` until a top-up, or on a paid plan the next month.

## When credit runs out, or a plan goes unpaid

- On the free plan, an account whose credit is used cannot run a sandbox. Its running sandboxes are stopped, and what it ran past its credit is shown as a balance owed. Its stopped sandboxes and snapshots are kept for 30 days, and then deleted, with the email its sandboxes received. The account itself stays open.
- So are those of an account with no card saved, and of one on a paid plan that owes: a month closed with more used than its plan's credits and its top-ups paid for, and the next month's credits have not covered it. Running out of credits inside a month is not owing; a month that closes short is.
- It is emailed when the 30 days begin, a week before they end, and the day before. The console says the date on every page, and `lapse` in `GET /v1/billing` says why (`no_plan`, `out_of_credit` or `unpaid`) and when (`deletesAt`).
- A top-up that covers what is owed, a card saved or a plan started before then keeps them. To keep some files, do that and copy them out.

## Stopped sandboxes and snapshots

| Size | Running, an hour | Stopped, an hour | Stopped, a month | Memory kept, a month |
| --- | --- | --- | --- | --- |
| tiny | $0.0135 | $0.0007 | $0.49 | $0.99 |
| small | $0.027 | $0.0014 | $0.99 | $1.97 |
| medium | $0.054 | $0.0027 | $1.97 | $3.94 |
| large | $0.108 | $0.0054 | $3.94 | $7.88 |

- A stopped sandbox keeps its whole disk until you delete it, at 5% of its running price, by the second. An archived one costs the same.
- One stopped with its memory kept costs 10% of its running price until it starts again.
- Your 10 oldest snapshots are free. Each one past them is $1.70 a month, by the second, until you delete it.
- Both are paid like running time: from the plan's credits, then the top-ups.
- Only running sandboxes count toward a plan's running count. Keep as many stopped as you like.

## The top-up bonus

A top-up of $200 or more adds more credits than it costs. The bonus is 2% at $200 and grows evenly on a log scale to 25% at $10,000, and stays at 25% above that. The percent is rounded to one place, and what it adds to the cent.

| You pay | Bonus | You get |
| --- | --- | --- |
| $200 | +2% | $204 |
| $500 | +7.4% | $537 |
| $1,000 | +11.5% | $1,115 |
| $2,000 | +15.5% | $2,310 |
| $5,000 | +20.9% | $6,045 |
| $10,000 | +25% | $12,500 |

- Below $200 a top-up adds what it costs.
- The bonus is credits like the rest of the top-up: spent after the plan's credits, and it does not expire. It is never paid out as money.
- Usage is charged at list price however much is used. The bonus is the only discount.

## Where the account stands

`GET /v1/billing`

```shell
curl -X GET https://agental.io/v1/billing \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

- Amounts are millionths of a US dollar: `1500000` is $1.50.
- `usedMicros` is the month's usage at list price, which is what is charged.
- `discount` is kept for older clients and is always `0`, `0` and null: the volume discount it described gave way to the top-up bonus.
- `includedMicros` is what the plan includes this month, and `topUpMicros` what is left of the top-ups.
- `canRun` is false when a new sandbox would be refused, and `reason` says why: `billing_required` (no card saved) or `out_of_credit`.
- `free` is set while the account is on the free plan: `cardSaved`, whether it has saved a card and had its credit; `paid`, whether it has paid for anything; and `unpaidUnits`, how many small sandboxes it runs at once until it has. `plan` is the free plan then, with `includedMicros` 0, and `period` runs from where its use was last settled to the next month's start.
- `lapse` is set while the account has no card saved, has used its credits, or owes, and still holds sandboxes or snapshots: `reason` is `no_plan`, `out_of_credit` or `unpaid`, `lapsedAt` is when that began, and `deletesAt` when they are deleted. It is null otherwise.
- `stoppedMicros` and `snapshotMicros` are the parts of `usedMicros` that are stopped sandboxes and snapshots past the free ones, and `burstMicros` the part that is this month's burst fees.
- `plan` has the plan's `runningUnits` and `freeBurstUnits`, its running count and free burst in small sandboxes.
- `carriedMicros` is what an earlier month ran past its plan and its top-ups. This month's credits pay it first.

## What is sold

`GET /v1/billing/plans`

```shell
curl -X GET https://agental.io/v1/billing/plans \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

It needs no key. `tiers` are the plans, each with its `runningUnits` and `freeBurstUnits` (`sandboxesAtOnce` and `burst` are kept for older clients), `burstFee` the burst fee's `halfLifeMinutes`, `feeMicrosPerGib` and `defaultBudgetMicros`, `topUps` the top-ups offered as a choice, each with what it adds (`micros`), its `bonusMicros` and `bonusPercent`, `topUpRange` the smallest and largest, `topUpBonus` the bonus, `free` the free plan's terms (`creditMicros`, the credit a saved card gives once, and `unpaidUnits`), and `plans` the list price an hour of each size. `volumeDiscount` is kept for older clients and is always one step of 0%.

## Buy a top-up

`POST /v1/billing/checkout`

```shell
curl -X POST https://agental.io/v1/billing/checkout \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topUp":500}'
```

- `topUp` is how many US dollars to pay: a whole number from 15 to 100000. $500 adds $537.
- It answers with `url`, the payment page. A person opens it and pays, and nothing is charged before. The top-up shows in `GET /v1/billing` within a minute of payment.
- `{ "plan": "plan100" }` starts a plan the same way: `plan100`, `plan500` or `plan2000`. An account that has a plan is moved to the other at once: `url` is null and `changed` is true. To go back to the free plan, cancel in the billing portal.
- `{ "card": true }` opens the page that saves a card for the free plan, charging nothing; once saved, the account gets its credit. It is refused with `409 card_saved` when a card is saved already.

> **Warning:** An agent can start a checkout but cannot pay. Give the url to the person whose account it is.

> **Tip:** From the CLI: `agental billing`, `agental billing prices` and `agental billing top-up 500`.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)