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.

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.

• 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#

• 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.

• 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#

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#

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#

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.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]